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Integrated File System APIs 


QlgAccess() through writev() and Process a Path Name Exit 
Program 


The integrated file system APIs can perform operations on directories, files, and related objects in the file 
systems accessed through the integrated file system interface. 


The integrated file system APIs (QlgAccess() through writev() and Process a Path Name Exit Program) are: 

e OlgAccess() (Determine file accessibility (using NLS-enabled path name)) determines whether a 
file can be accessed in a particular manner. 

e@ QlgAccessx() (Determine File Accessibility for a Class of Users (using NLS-enabled path name)) 
determines whether a file can be accessed in a particular manner by a specified class of users.*& 

e QlgChdird (Change current directory (using NLS-enabled path name)) makes the directory named 
by path the new current directory. 

e@ QlgChmodQ (Change file authorizations (using NLS-enabled path name)) changes the mode of the 
file or directory specified in path. 

e@ QlgChown() (Change owner and group of file (using NLS-enabled path name)) changes the owner 
and group of a file. 

e@ QlgCreat() (Create or rewrite file (using NLS-enabled path name)) creates a new file or rewrites an 
existing file so that it is truncated to zero length. 

e@ OlgCreat64Q (Create or rewrite a file (large file enabled and using NLS-enabled path name)) 
creates a new file or rewrites an existing file so that it is truncated to zero length. 


e@ OlegCvtPathToQS YSObjName() (Resolve integrated file system path name into QSYS object name 


(using NLS-enabled path name)) resolves a given integrated file system path name into the 
three-part QSYS.LIB file system name: library, object, and member. 


e@ OlgGetAttrd (Get attributes (using NLS-enabled path name)) gets one or more attributes, on a 
single call, for the object that is referred to by the input Path_Name. 

e QlgGetcwdQ (Get current directory (using NLS-enabled path name)) determines the absolute path 
name of the current directory and returns a pointer to it. 


e QlgGetPathFromFileIDQ (Get path name of object from its file ID (using NLS-enabled path 
name)) determines an absolute path name of the file identified by fileid and stores it in buf. 


e QlgGetpwnam() (Get user information for user name (using NLS-enabled path name)) returns a 


pointer to an object of type struct qplg_passwd containing an entry from the user database with a 
matching name. 


e OlgGetpwnam_r() (Get user information for user name (using NLS-enabled path name)) updates 
the qplg_passwd structure pointed to by pwd and stores a pointer to that structure in the location 
pointed to by result. 

e OlgGetpwuid() (Get user information for user ID (using NLS-enabled path name)) returns a pointer 
to an object of type struct qplg_passwd containing an entry from the user database with a matching 
user ID (UID). 

e QlgGetpwuid_rQ (Get user information for user ID (using NLS-enabled path name)) updates the 
qplg_passwd structure pointed to by pwd and stores a pointer to that structure in the location 
pointed to by result. 


e QlegLchownQ (Change owner and group of symbolic link (using NLS-enabled path name)) changes 


the owner and group of a file. 
QlgLinkQ (Create link to file (using NLS-enabled path name)) provides an alternative path name 
for the existing file so that the file can be accessed by either the existing name or the new name. 
QlgLstatQ (Get file or link information (using NLS-enabled path name)) gets status information 
about a specified file and places it in the area of memory pointed to by buf. 
QlgLstat64Q (Get file or link information (large file enabled and using NLS-enabled path name)) 
gets status information about a specified file and places it in the area of memory pointed to by buf. 
QlgMkdirQ (Make directory (using NLS-enabled path name)) creates a new, empty directory 
whose name is defined by path. 

lgMkfifoQ (Make FIFO special file (using NLS-enabled path name)) creates a new FIFO special 
file whose name is defined by path. 
QlgOpen() (Open a file (using NLS-enabled path name)) opens a file or creates a new, empty file 
whose name is defined by path and returns a number called a file descriptor. 


QlgOpen64() (Open file (large file enabled and using NLS-enabled path name)) opens a file and 
returns a number called a file descriptor. 


QlgOpendir() (Open directory (using NLS-enabled path name)) opens a directory so it can be read. 


QlgPathconf() (Get configurable path name variables (using NLS-enabled path name)) lets an 
application determine the value of a configuration variable (name) associated with a particular file 
or directory (path). 

QlgProcessSubtree(Q) (Process a path name (using NLS-enabled path name)) searches the directory 
tree under a specific path name. 

QlgReaddirQ (Read directory entry (using NLS-enabled path name)) returns a pointer to a structure 
describing the next directory entry in the directory stream associated with dirp. 

QlgReaddir_rQ (Read directory entry (using NLS-enabled path name)) initializes a structure that is 
referenced by entry to represent the next directory entry in the directory stream that is associated 
with dirp. 

QlgReadlink() (Read value of symbolic link (using NLS-enabled path name)) places the contents of 
the symboliclink path in the buffer buf. 


QlgRenameKeep() (Rename file or directory, keep "new" if it exists (using NLS-enabled path 
name)) renames a file or a directory specified by old to the name given by new. 
QlgRenameUnlinkQ (Rename file or directory, unlink "new" if it exists (using NLS-enabled path 
name)) renames a file or a directory specified by old to the name given by new. 

QlgRmdirQ (Remove directory (using NLS-enabled path name)) removes a directory, path, 
provided that the directory is empty; that is, the directory contains no entries other than 'dot' (.) or 
‘dot-dot' (..). 

QlgSaveStgFree() (Save Storage Free (using NLS-enabled path name)) calls a user-supplied exit 


program to save an *STMF iSeries object type and, upon successful completion of the exit 
program, frees the storage for the object and marks the object as storage freed. 


QlgSetAttrO (Set attributes (using NLS-enabled path name)) sets one of a set of defined attributes, 
on each call, for the object that is referred to by the input *Path_Name. 

QlgStatQ (Get file information (using NLS-enabled path name)) gets status information about a 
specified file and places it in the area of memory pointed to by the buf argument. 


QlgStat64(Q (Get file information (large file enabled and using NLS-enabled path name)) gets status 


information about a specified file and places it in the area of memory pointed to by the buf 
argument. 


e QOlgStatvfsQ (Get file system information (using NLS-enabled path name)) gets status information 
about the file system that contains the file named by the path argument. 

e OlgStatvfs64Q (Get file system information (64-bit enabled and using NLS-enabled path name)) 
gets status information about the file system that contains the file named by the path argument. 

e QlegSymlinkQ (Make symbolic link (using NLS-enabled path name)) creates the symbolic link 
named by slink with the value specified by pname. 

e QlgUnlinkQ (Remove link to file (using NLS-enabled path name)) removes a directory entry that 
refers to a file. 

e OlgUtime( (Set file access and modification times (using NLS-enabled path name)) sets the access 
and modification times of path to the values in the utimbuf structure. 

e QPOFPTOS (Perform Miscellaneous File System Functions) performs a variety of file system 
functions.*& 


e Qp0lCvtPathToQS YSObjName() (Resolve integrated file system path name into QSYS object 


name) resolves a given integrated file system path name into the three-part QSYS.LIB file system 
name: library, object, and member. 


e@ QPOLFLOP (Perform file system operation) performs miscellaneous file system operations. 


e@ Qp0lGetAttrO (Get attributes) gets one or more attributes, on a single call, for the object that is 
referred to by the input Path_Name. 


e@ Qp0lGetPathFromFileIDQ (Get path name of object from its file ID) determines an absolute path 
name of the file identified by fileid and stores it in buf. 


e@ Qp0lOpen( (Open file) opens a file and returns a number called a file descriptor. 


e@ Qp0lProcessSubtree() (Process a path name) searches the directory tree under a specific path name. 


It selects and passes objects, one at a time, to an exit program that is identified on its call. The exit 
program can be either a procedure or a program. 


e@ Qp0lRenameKeep() (Rename file or directory, keep new if it exists) renames a file or a directory 
specified by old to the name given by new. 


e@ Qp0lRenameUnlink( (Rename file or directory, unlink new if it exists) renames a file or a 
directory specified by old to the name given by new. 

e QPOLROR (Retrieve Object References) retrieves information about Integrated File System 
references on an object.%& 


e@ Qp0lSaveStgFreeQ (Save Storage Free) calls a user-supplied exit program to save an *STMF 


iSeries object type and, upon successful completion of the exit program, frees the storage for the 
object and marks the object as storage freed. 


@ QpOlSetAttrO (Set attributes) renames a file or a directory specified by old to the name given by 
new. 


e@ Qp0lUnlinkd (Remove link to file) removes a directory entry that refers to a file. 


e Qp0zPipe( (Create interprocess channel with sockets) creates a data pipe that can be used by two 
processes. 


e qsygetgroups() (Get Supplemental Group IDs) returns the supplemental group IDs associated 
with the calling thread.*& 


e@ qsysetegid() (Set effective group ID) sets the effective group ID to gid. 
e@ qsyseteuid( (Set effective user ID) sets the effective user ID to uid. 
e@ qsysetgidQ (Set group ID) sets the real, effective and saved groups to gid. 


e “qsysetgroups() (Set Supplemental Group IDs) sets the supplementary group IDs of the calling 
thread. 


@ qsysetregid() (Set real and effective group IDs) is used to set the real and effective group IDs. The 
real and effective group IDs may be set to different values in the same call. 

e@ qsysetreuid( (Set real and effective user IDs) sets the real and effective user IDs to the values 
specified by ruid and euid. 

e@ qsysetuid( (Set user ID) sets the real, effective, and saved user ID to uid. 


e@ QOZNFRTVE (Retrieve network file system export entries) returns the list of Network File System 


(NES) export entries for objects currently exported to NFS clients or for objects referenced in the 
/etc/exports file. 


e readQ (Read from Descriptor) reads nbyte bytes of input into the memory area indicated by buf. 

e readdir() (Read directory entry) returns a pointer to a dirent structure describing the next directory 
entry in the directory stream associated with dirp. 

e readdir_r() (Read directory entry) initializes the dirent structure that is referenced by entry to 
represent the next directory entry in the directory stream that is associated with dirp. 

e readdir_r_ts64( (Read directory entry) initializes the dirent structure that is referenced by entry to 
represent the next directory entry in the directory stream that is associated with dirp. 

e readlink( (Read value of symbolic link) places the contents of the symbolic link path in the buffer 
buf. 

e readvQ (Read from Descriptor Using Multiple Buffers) is used to receive data from a file or socket 
descriptor. 

@ rename() (Rename file or directory) can be used to rename a file or directory with the semantics of 
Qp0lRenameUnlink() or QpOIRenameKeep(). 

e rewinddir( (Reset directory stream) 'rewinds' the position of an open directory stream to the 
beginning. 

e rmdirQ (Remove directory) removes a directory, path, provided that the directory is empty; that is, 
the directory contains no entries other than 'dot' (.) or 'dot-dot' (..). 

e stat() (Get file information) gets status information about a specified file and places it in the area of 
memory pointed to by the buf argument. 

e stat64() (Get file information (large file enabled)) gets status information about a specified file and 
places it in the area of memory pointed to by the buf argument. 

e statvfsQ (Get file system information) gets status information about the file system that contains the 
file named by the path argument. 

e statvfs64Q (Get file system information (large file enabled)) gets status information about the file 
system that contains the file named by the path argument. 

e symlinkQ (Make symbolic link) creates the symbolic link named by slink with the value specified 
by pname. 

e sysconf() (Get system configuration variables) returns the value of a system configuration option. 

@ umask() (Set authorization mask for job) changes the value of the file creation mask for the current 
job to the value specified in cmask. 

e@ unlinkQ (Remove link to file) removes a directory entry that refers to a file. 


e@ utime( (Set file access and modification times) sets the access and modification times of path to 
the values in the utimbuf structure. 


@ write() (Write to Descriptor) writes nbyte bytes from buf to the file or socket associated with 
file_descriptor. 


@ writevQ (Write to Descriptor Using Multiple Buffers) is used to write data to a file or socket 
descriptor. 
The integrated file system exit programs are: 


e Process a Path Name is called by the Qp0IProcessSubtreeQ) API for each object in the API's search 
that meets the caller's selection criteria. This exit program must be provided by the user. 


e@ Save Storage Free is called by the QpO0ISaveStgFree() API to save an *STMF iSeries object type. 


In addition to the functions above, the following functions, which are described in the Sockets APIs, also 
can operate on files in the integrated file system. 


[Other Functions that Operate on Files 
[Function Description 


givedescriptor() Give file access to another job 
Give socket access to another job 
selectQ) Check I/O status of multiple file descriptors 
Wait for events on multiple sockets 
takedescriptorQ Take file access from another job 
Take socket access from another job 
Note: These functions use header (include) files from the library QSYSINC, which is optionally installable. 


Make sure QSYSINC is installed on your system before using any of the functions. See Header Files for 
UNIX-Type Functions) for the file and member name of each header file. 


Many of the terms used in this chapter, such as current directory, file system, path name, and link, are 
explained in the Integrated File System book. The API Examples also shows an example of using several 
integrated file system functions. 


To determine whether a particular function updates the access, change, and modification times of the object 
on which it performs an operation, see Integrated File System APIs--Time Stamp Updates. 
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QlgAccess()--Determine File Accessibility 
(using NLS-enabled path name) 


Syntax 


#include <unistd.h> 


int QlgAccess(const Qlg_Path_Name_T *path, int amode); 


Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgAccess() function, like the access() function, determines whether a file can be accessed in a 
particular manner. The difference is that the QlgAccess() function takes a pointer to a Qlg_Path_Name_T 
structure, while access() takes a pointer to a character string. 


Limited information on the path parameter is provided here. For more information on the path parameter 
and for a discussion of other parameters, authorities required, return values, and related information, see 
access()--Determine File Accessibility. 


Parameters 


path 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path 
name for the file to be checked for accessibility. For more information on the Qlg_ Path_Name_T 
structure, see Path name format. 


Related Information 


e@ access()--Determine File Accessiblity 
@ accessx()--Determine File Accessibility for Class of Users 
@ *faccessx()--Determine File Accessibility for Class of Users *& 


e@ QleAccessx()--Determine File Accessibility for Class of Users (using NLS-enabled path name) 
“4 


e@ QlgChmod--Change File Authorizations (using NLS-enabled path name) 


e QlgStat(--Get File Information (using NLS-enabled path name) 


Example 
The following example determines how a file is accessed: 


#include <stdio.h> 
#include <unistd.h> 


main () 


{ 


[BRK KKK KK KKK I KE I KK KK I  / 
/* Defininitons */ 
[BRK KKK KK KK KK I I KK KK / 
#define mypath "/" 
const char US_const[3]= "US"; 
const char Language_const[4] ="ENU"; 
typedef struct pnstruct 
{ 
Qlg_Path_Name_T qlg_struct; 
char pn[100]; /* This array size must be >= the */ 
/* length of the path name or this must */ 
/* be a pointer to the path name. */ 


}; 
struct pnstruct path; 


[BRK KK KK KK KK KI I EI I EE I I / 


/* Initialize Qlg_Path_Name_T parameters a: 
[BRK KKK KK KK KK EE I I EE I EK I / 


memset ((void*)path name, 0x00, sizeof(struct pnstruct)); 
path.glg_struct.CCSID = 37; 

memcpy (path.gqlg_struct.Country_ID, US_const,2); 

memcpy (path.gqlg_struct.Language_ID, Language_const, 3); 
path.glg_struct.Path_Type = QLG_CHAR_SINGLE; 
path.gqlg_struct.Path_Length = sizeof (mypath)-1; 
path.gqlg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (path.pn,mypath, sizeof (mypath) -1); 


if (QlgAccess((Qlg_Path_Name_T *)&path, F_OK) != 0) 
printf("'Ss' does not exist!\n", mypath); 
else { 
if (QlgAccess((Qlg_Path_Name_T *)&path, R_OK) == 0) 
printf ("You have read access to '%s'\n", mypath); 
if (QlgAccess((Qlg_Path_Name_T *)&path, W_OK) == 0) 
printf ("You have write access to '%s'\n", mypath); 
if (QlgAccess((Qlg_Path_Name_T *)&path, X_OK) == 0) 


printf ("You have search access to '%s'\n", mypath) ; 


Output: 


The output from a user with read and execute access is: 


You have read access to '/'! 
You have write access to '/' 
You have search access to '‘'/' 
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a 


QlgAccessx()--Determine File Accessibility for a 
Class of Users (using NLS-enabled path name) 


Syntax 


#include <unistd.h> 


int QlgAccessx(const Qlg_Path_Name_T *path, int amode, int who); 
Service Program Name: QPOLLIB1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgAccessx() function, like the accessx() function, determines whether a file can be accessed in a particular 
manner by a specified class of users. The difference is that the QlgAccessx() function takes a pointer to a 
Qlg Path_Name_T structure, while accessx() takes a pointer to a character string. 


Limited information on the path parameter is provided here. For more information on the path parameter and for 
a discussion of other parameters, authorities required, return values, and related information, see 
accessx()--Determine File Accessibility for a Class of Users. 


Parameters 


path 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path name 
for the file to be checked for accessibility. For more information on the Qlg_Path_Name_T structure, see 
Path name format. 


Related Information 


e@ access()--Determine File Accessiblity 

@ accessx()--Determine File Accessibility for a Class of Users 

e@ faccessx()--Determine File Accessibility for a Class of Users 

e@ QlgAccess()--Determine File Accessibility (using NLS-enabled path name) 
e@ QlgChmod(--Change File Authorizations (using NLS-enabled path name) 


e@ QlgStatQ--Get File Information (using NLS-enabled path name) 


Example 
The following example determines how a file is accessed: 


#include <stdio.h> 
#include <unistd.h> 


main () 


{ 


[ORK KK KK KK A A A AA A AA A I / 
/*  Defininitons beh 
[ORK KK KK KK A AA A A AA I  / 
#define mypath "/myfile" 
const char US_const[3]= "US"; 
const char Language_const[4] ="ENU"; 
typedef struct pnstruct 
{ 
Qlg_Path_Name_T gqlg_struct; 
char pn[100]; /* This array size must be >= the */ 
/* length of the path name or this must */ 
/* be a pointer to the path name. */ 


}; 
struct pnstruct path; 


[ORK KK KK KK KK AA A A AA I 


/* Initialize Qlg_Path_Name_T parameters * / 
[ORK KK KK KK A A A A A AAA A 
memset ((void*) &path, 0x00, sizeof(struct pnstruct)); 
path.qlg_struct.CCSID = 37; 

memcpy (path.qlg_struct.Country_ID,US_const,2); 

memcpy (path.qlg_struct.Language_ID, Language_const, 3); 
path.qlg_struct.Path_Type = QLG_CHAR_SINGLE; 
path.qlg_struct.Path_Length = sizeof (mypath)-1; 
path.qlg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (path.pn,mypath, sizeof (mypath) -1); 


if (QlgAccessx((Qlg_Path_Name_T *) &path, R_OK, ACC_OTHERS) == 0) 
printf("Someone besides the owner has read access to '%Ss'\n", mypath); 
if (QlgAccessx((Qlg_Path_Name_T *) &path, W_OK, ACC_OTHERS) == 0) 
printf("Someone besides the owner has write access to '%s'\n", 
mypath) ; 


if (QlgAccessx((Qlg_Path_Name_T *) &path, X_OK, ACC_OTHERS) = 
printf("Someone besides the owner has search access to ' 
mypath) ; 
} 


= 0) 
&s'\n", 


Output: 


In this example QlgAccessx() was called on '/myfile'. The following would be the output if someone other than 
the owner has *R authority, someone besides the owner has *W authority, and noone other than the owner has 
*X authority. 


Someone besides the owner has read access to '/' 
Someone besides the owner has write access to '/' 


< 
API introduced: V5R2 
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QlgChdir()--Change Current Directory (using 
NLS-enabled path name) 


Syntax 


#include <unistd.h> 


int QlgChdir(const Qlg_Path_Name_T *path); 
Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgChdir() function, like the chdir() function, makes the directory named by path the new current 
directory. The difference is that the QlgChdir() function takes a pointer to a Qlg Path _Name_T structure, 
while chdir() takes a pointer to a character string. 


Limited information on the path parameter is provided here. For more information on the path parameter 
and for a discussion of other parameters, authorities required, return values, and related information, see 
chdirQ--Change Current Directory. 


Parameters 


path 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path 
name of the directory that should become the current directory. For more information on the 
Qlg_ Path_Name_T structure, see Path name format. 


Related Information 


e chdirQ--Change Current Directory 
e@ QleGetcwd(--Get Current Directory (using NLS-enabled path name) 


e “fchdir()--Change Current Directory by Descriptor 


Example 


The following example uses QlgChdir(Q: 


#include <stdio.h> 


#include <unistd.h> 


main() { 
#define mypath "/tmpXXxX" 
const char US_const[3]= "US"; 
const char Language_const[4] ="ENU"; 


typedef struct pnstruct 
{ 
Qlg_Path_Name_T qlg_struct; 
char pn[100]; /* This array size must be >= the */ 
/* length of the path name or this */ 
/* this be a pointer to the path name. */ 


}; 
struct pnstruct path; 


[RK KK KK KK KK KK KK KK KK KR KK KK / 


/* Initialize Qlg_Path_Name_T parameters a A 
[RK KK KK KK KK KK KK I RK KK KK / 
memset ((void*) &path, 0x00, sizeof(struct pnstruct)); 
path.glg_struct.CCSID = 37; 

memcpy (path.gqlg_struct.Country_ID, US_const,2)j; 

memcpy (path.gqlg_struct.Language_ID, Language_const, 3); 
path.glg_struct.Path_Type = QLG_CHAR_SINGLE; 
path.gqlg_struct.Path_Length = sizeof (mypath)-1; 
path.qlg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (path.pn,mypath, sizeof (mypath) -1); 


if (QlgChdir((Qlg_Path_Name_T *)&path) != 0) 
{ 
printf ("QlgChdir() to /tmpXXX failed."); 
} 
else 
{ 
printf ("QlgChdir() changed the current directory "); 
printf("to '%Ss'.\n", mypath); 
} 


Output: 


QlgChdir() changed the current directory to '/tmpxxx'. 
(or if error, such as path not found: QlgChdir() to /tmpXXX failed. 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


QigChmod()--Change File Authorizations (using 
NLS-enabled path name) 


Syntax 


#include <sys/stat.h> 


int QlgChmod(Qlg_Path_Name_T *path, mode_t mode); 


Service Program Name: QPOLLIB1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgChmod() function, like the chmod() function, changes 2#*S_ISUID, S_ISGID, and the permission bits of 
the file or directory specified in path to the corresponding bits specified in mode. “The difference is that the 
QlgChmod() function takes a pointer to a Qlg_Path_Name_T structure, while chmod() takes a pointer to a 
character string. 


Limited information on the path parameter is provided here. For more information on the path parameter and for 
a discussion of other parameters, authorities required, return values, and related information, see 
chmod()--Change File Authorizations. 


Parameters 


path 


(Input) A pointer to a Qlg_Path_Name_T structure that contains the path name or a pointer to the path 
name of the file whose mode is being changed. For more information on the Qlg_ Path_Name_T 
structure, see Path name format. 


Related Information 


e@ chmod()--Change File Authorizations 
e@ QlgChown()--Change Owner and Group of File (using NLS-enabled path name) 
e@ QlgMkdirQ--Make Directory (using NLS-enabled path name) 


e@ QlgStatQ--Get File Information (using NLS-enabled path name) 


Example 


The following example changes the permissions for a file: 


#include 
#include 
#include 
#include 
#include 


main() { 


<stdio.h> 
<sys/stat.h> 
<sys/types.h> 
<fentl.h> 
<QpOlstdi.h> 


int file_descriptor; 


struct 


stat info; 


#define mypath "temp.file" 


const char US_const[3]= "US"; 
const char Language_const [4] ="ENU"; 
typedef struct pnstruct 


{ 


Qlg_Path_Name_T qlg_struct; 


char pn[100]; 


}; 


/* This array size must be >= the */ 


/* length of the path name or this must */ 
/* be a pointer to the path name. */ 


struct pnstruct path; 


[KKK KK KK KK A A A A A A A  / 


Le Initialize Qlg_Path_Name_T parameters 
[ORK KK KK KK A A AA A AA A RK / 


memset ((void*) &path, 0x00, sizeof(struct pnstruct)); 
path.qlg_struct.CCSID = 37; 

memcpy (path.qlg_struct.Country_ID,US_const,2); 
memcpy (path.qlg_struct.Language_ID, Language_const, 3); 
path.qlg_struct.Path_Type = QLG_CHAR_SINGLE; 


path.qlg_struct.Path_Length = sizeof (mypath)-1 


path.gqlg_struct.Path_Name_Delimiter[0] = '/'; 
memcpy (path.pn,mypath, sizeof (mypath) -1); 
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er 


if ((file_descriptor = QlgCreat ((Qlg_Path_Name_T *)&path, S_IWUSR)) == -1) 
perror("QlgCreat() error"); 
else { 


close(file_descriptor) ; 

QlgStat ((Qlg_Path_Name_T *)&path, &info); 

printf ("original permissions were: %080\n", 

if (QlgChmod((Qlg_Path_Name_T *) &path, S_IRWXU|S_IRWXG) '= 0) 
perror("QlgChmod() error"); 


else 


{ 


QlgStat ((Qlg_Path_Name_T *)&path, &info); 
printf ("after QlgChmod(), permissions are: 


} 


QlgUnlink ((Qlg_Path_Name_T *) &path); 


} 
Output: 


original 


permissions were: 00100200 


info.st_mode); 


S080\n", 


info.st_mode); 


after QlgChmod(), permissions are: 00100770 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


QlgChown()--Change Owner and Group of File 
(using NLS-enabled path name) 


Syntax 


#include <unistd.h> 


int QlgChown(Qlg_Path_Name_T *path, uid_t owner,gid_t 
group); 
Service Program Name: QPOLLIB1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgChown() function, like the chown() function, changes the owner and group of a file. The difference is 
that the QlgChown() function takes a pointer to a Qlg_Path_Name_T structure, while chown() takes a pointer to 
a character string. 


Limited information on the path parameter is provided here. For more information on the path parameter and for 
a discussion of other parameters, authorities required, return values, and related information, see 
chown()--Change Owner and Group of File. 


Parameters 


path 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path name 
of the file whose owner and group are being changed. For more information on the Qlg_Path_Name_T 
structure, see Path name format. 


Related Information 


e@ chown()--Change Owner and Group of File 
e@ QlgChmod()--Change File Authorizations (using NLS-enabled path name) 
e QlgLstatuQ--Get File or Link Information (using NLS-enabled path name) 


e@ QlgStatQ--Get File Information (using NLS-enabled path name) 


Example 
The following example changes the owner and group of a file: 


#include <stdio.h> 
#include <unistd.h> 
#include <sys/stat.h> 
#include <sys/types.h> 
#include <fcntl.h> 
#include <QpOlstdi.h> 


main() { 
int file_descriptor; 
struct stat info; 


#define mypath "temp.file" 
const char US_const[3]= "US"; 
const char Language_const [4] ="ENU"; 
typedef struct pnstruct 
{ 
Qlg_Path_Name_T gqlg_struct; 
char pn[100]; /* This array size must be >= the */ 
/* length of the path name or this must */ 
/* be a pointer to the path name. */ 


‘i 
struct pnstruct path; 


[OK KK KKK KK a I A A AA RK  / 


/* Initialize Qlg_Path_Name_T parameters * / 
[OK KK KK KK A A A A A I  / 
memset ((void*) &path, 0x00, sizeof(struct pnstruct)); 
path.qlg_struct.CCSID = 37; 
memcpy (path.qlg_struct.Country_ID,US_const,2); 
memcpy (path.qlg_struct.Language_ID, Language_const, 3); 
path.qlg_struct.Path_Type = QLG_CHAR_SINGLE; 
path.qlg_struct.Path_Length = sizeof (mypath)-1; 
path.qlg_struct.Path_Name_Delimiter[0] = '/'; 
memcpy (path.pn,mypath, sizeof (mypath) —-1); 


if ((file_descriptor = QlgCreat ((Qlg_Path_Name_T *)&path, S_IRWXU)) == -1) 
perror("creat() error"); 
else { 


close(file_descriptor) ; 

QlgStat ((Qlg_Path_Name_T *)&path, &info); 

printf ("original owner was %d and group was %d\n", info.st_uid, 
info.st_gid); 


if (QlgChown ((Qlg_Path_Name_T *)é&path, 152, 0) != 0) 
perror("QlgChown() error"); 
else { 


QlgStat ((Qlg_Path_Name_T *)&path, &info); 
printf("after QlgChown(), owner is %d and group is %d\n", 
info.st_uid, info.st_gid)j; 
} 
QlgUnlink ((Qlg_Path_Name_T *) &path); 


} 
Output: 


original owner was 137 and group was 0 
after QlgChown(), owner is 152 and group is 0 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


QlgCreat()--Create or Rewrite File (using 
NLS-enabled path name) 


Syntax 


#include <fcntl.h> 


int QlgCreat (Qlg_Path_Name_T *path, mode_t mode); 
Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgCreat() function, like the creat() function, creates a new file or rewrites an existing file so that it is 
truncated to zero length. The difference is that the QlgCreat() function takes a pointer to a 
Qlg_ Path_Name_T structure, while creat() takes a pointer to a character string. See openQ--Open File for 


more details on how the function call 


QlgCreat (path, mode) ; 


is equivalent to the call 


QlgOpen (path, O_CREAT|O_WRONLY|O_TRUNC, mode) ; 


Limited information on the path parameter is provided here. For more information on the path parameter 
and for a discussion of other parameters, authorities required, return values, and related information, see 
creat()--Create or Rewrite File or open()--Open File. 


Parameters 


path 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path 
name of the file to be created or rewritten. For more information on the Qlg_ Path_Name_T 
structure, see Path name format. 


Related Information 


@ creat()--Create or Rewrite File 


e QlgCreat64()--Create or Rewrite a File (large file enabled and using NLS-enabled path name) 


Example 


The following example creates a file: 


#include <stdio.h> 
#include <fcntl.h> 
#include <Qp0lstdi.h> 


main() { 


} 


char text[]="This is a test"; 

int file_descriptor; 
#define mypath "creat.file" 

const char US_const[3]= "US"; 

const char Language_const[4] ="ENU"; 
typedef struct pnstruct 

{ 


Qlg_Path_Name_T qlg_struct; 
char pn[100]; /* This array size must be >= the */ 
/* length of the path name or this must */ 
/* be a pointer to the path name. */ 
}; 
struct pnstruct path; 


[BR KK KKK KK KK KK KK KK EE RK RK KK KKK / 


/* Initialize Qlg_Path_Name_T parameters */ 
[KKK KKK KK KK KK KK RR KK RK RR RK KK I / 


memset ((void*) &path, 0x00, sizeof(struct pnstruct)); 
path.glg_struct.CCSID = 37; 

memcpy (path.gqlg_struct.Country_ID, US_const,2)j; 

memcpy (path.gqlg_struct.Language_ID, Language_const, 3); 
path.glg_struct.Path_Type = QLG_CHAR_SINGLE; 
path.gqlg_struct.Path_Length = sizeof (mypath)-1; 


path.qlg_struct.Path_Name_Delimiter[0] = '/'; 
memcpy (path.pn,mypath, sizeof (mypath) -1); 
if ((file_descriptor = 
QlgCreat ((Qlg_Path_Name_T *) &path, S_IRUSR S_IWUSR)) < 0) 
perror ("QlgCreat() error"); 
else { 


write(file_descriptor, text, strlen(text)); 
close(file_descriptor) ; 
QlgUnlink((Qlg_Path_Name_T *) &path); 


} 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


QligCreat64()--Create or Rewrite a File (large file 
enabled and using NLS-enabled path name) 


Syntax 


#include <fcntl.h> 


int QlgCreat64(Qlg_Path_Name_T *path,mode_t mode); 
Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgCreat64() function, like the creat64() function, creates a new file or rewrites an existing file so 
that it is truncated to zero length. The difference is that the QlgCreat64() function takes a pointer to a 
Qlg_ Path_Name_T structure, while creat64() takes a pointer to a character string. See creat64()--Create or 


Rewrite a File (Large File Enabled) and open64()--Open File (Large File Enabled) for more details on how 
the function call 


QlgCreat 64 (path, mode) ; 


is equivalent to the call 


QlgOpen64 (path, O_CREAT|O_WRONLY|O_TRUNC, mode); 


Limited information on the path parameter is provided here. For more information on the path parameter 
and for a discussion of other parameters, authorities required, return values, and related information, see 
creat64()--Create or Rewrite a File (Large File Enabled) or open64()--Open File (Large File Enabled). 


Parameters 


path 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path 
name of the file to be created or rewritten. For more information on the Qlg_ Path_Name_T 
structure, see Path name format. 


Related Information 


@ creat()--Create or Rewrite a File 


e creat64()--Create or Rewrite a File (Large File Enabled) 


Example 


The following example creates a file: 


#define _LARGE_FILE_API 


#include <stdio.h> 
#include <fcntl.h> 
#include <Qp0lstdi.h> 


main () 
{ 
char text[]="This is a test"; 
int: fds 
#define mypath "creat.file" 
const char US_const[3]= "US"; 
const char Language_const[4] ="ENU"; 


} 


typedef struct pnstruct 
{ 
Qlg_Path_Name_T qlg_struct; 
char pn[100]; /* This array size must be >= the */ 
/* length of the path name or this must */ 
/* be a pointer to the path name. */ 


}; 
struct pnstruct path; 


[BRK KKK KK KK KK I I KK KK / 


/* Initialize Qlg_Path_Name_T parameters * / 
[BRK KKK KK KK KK I EK KK / 
memset ((void*) &path, 0x00, sizeof(struct pnstruct)); 
path.glg_struct.CCSID = 37; 

memcpy (path.gqlg_struct.Country_ID, US_const,2); 

memcpy (path.gqlg_struct.Language_ID, Language_const, 3); 
path.glg_struct.Path_Type = QLG_CHAR_SINGLE; 
path.gqlg_struct.Path_Length = sizeof (mypath)-1; 
path.gqlg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (path.pn,mypath, sizeof (mypath) -1); 


if 
((fd = 
QlgCreat 64 ( 
(Qlg_Path_Name_T *)&path, S_IRUSR S_IWUSR) ) 
< 0) 
{ 
perror ("OQlgCreat64() error"); 
} 
else { 


write(fd, text, strlen(text)); 

close(fd); 

QlgUnlink((Qlg_Path_Name_T *) &path); 
} 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


QigCvtPathToQS YSObjName()-- Resolve 


Integrated File System Path Name into QSYS 
Object Name (using NLS-enabled path name) 


Syntax 


#include <qp0Olstdi.h> 


void QlgCvtPathToQSYSObjName ( 


Qlg_Path_Name_T *path_name, 


void 
char 
uint 
uint 
void 


Service Program Name: QPOLLIB2 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


For a description of this function and more information on the parameters, authorities required, return 


*qsys_info, 
format_name[8], 
bytes_provided, 
desired_CCSID, 

*error_code); 


values, error conditions, error messages, usage notes, and related information, see 


Qp0lCvtPathToQS YSObjName()-- Resolve Integrated File System Path Name into QSYS Object Name. 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


QlgGetAttr()--Get Attributes (using 
NLS-enabled path name) 


Syntax 


#include <Qp0lstdi.h< 

int QlgGetAttr 
(Qlg_Path_Name_T *Path_Name, 
Qp0l_AttrTypes_List_t *Attr_Array_ptr, 
char *Buffer_ptr, 
uint Buffer_Size_Provided, 
uint * Buffer_Size_Needed_ptr, 
uint *Num_Bytes_Returned_ptr, 
uint Follow_Symink, ...); 


Service Program Name: QPOLLIB2 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


For a description of this function and more information on the parameters, authorities required, return 
values, error conditions, error messages, usage notes, related information, and an example, see 


Qp01GetAttrQ--Get Attributes. 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


QligGetcwd()--Get Current Directory (using 
NLS-enabled path name) 


Syntax 


#include <unistd.h> 


Qlg_Path_Name_T *QlgGetcwd(Qlg_Path_Name_T *buf, 
size_t size); 


Service Program Name: QPOLLIB2 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgGetcwd() function, like the getewd() function, determines the absolute path name of the current 
directory and returns a pointer to it. The difference is that the pointer returned by QlgGetcwd() is a pointer 
to a Qlg_Path_Name_T structure that holds the absolute path name, while getewd() returns a pointer to a 
character string or buffer that contains the null-terminated absolute path name. 


Limited information on the buf parameter and on the size parameter is provided here. For more information 
on the parameters and for a discussion on authorities required, return values, and related information, see 
getcwd()--Get Current Directory. 


Parameters 


buf 


(Output) A pointer to a Qlg_Path_Name_T structure that holds the absolute path name of the 
current directory. The path name is not null-terminated within the structure. For more information 
on the Qlg_ Path_Name_T structure, see Path name format. 


size 


(Input) The number of bytes allocated for buf. 


Related Information 


@ getcwd()--Get Current Directory 


e QlgChdirQ--Change Current Directory (using NLS-enabled path name) 


Example 
The following example determines the current directory: 


#include <unistd.h> 
#include <stdio.h> 


main () 


{ 
#define mypath_cd "/tmp" 


const char US_const[3]= "US"; 
const char Language_const [4]="ENU"; 
typedef struct pnstruct 
{ 
Qlg_Path_Name_T qlg_struct; 
char pn[1024]; /* This size must be large enough */ 
/* to contain the path name. af: 


}; 


struct pnstruct path_cd; 
struct pnstruct path_cwd; 


[KKK KKK KR KR KK KK KK KK KK KK KK KR KK I  / 


/* Initialize Qlg_Path_Name_T parameters */ 
[KKK KKK KK KK KK KK KK KK KK KKK KK KK KK / 


memset ((void*)path name_cd, 0x00, sizeof(struct pnstruct)); 
path_cd.qlg_struct.CCSID = 37; 

memcpy (path_cd.qlg_struct.Country_ID,US_const, 2); 

memcpy (path_cd.qlg_struct.Language_ID, Language_const, 3); 
path_cd.qlg_struct.Path_Type = QLG _CHAR_SINGLE; 
path_cd.qlg_struct.Path_Length = sizeof (mypath_cd)-1; 
path_cd.glg_struct.Path_Name_Delimiter[0] = '/' 

memcpy (path_cd.pn, mypath_cd, sizeof (mypath_cd)-1); 


if (QlgChdir((Qlg_Path_Name_T *)path name_cd) != 0) 
perror("QlgChdir() error()"); 
else 


{ 


if (QlgGetcwd(Qlg_Path_Name_T *path_cwd, 


sizeof (struct pnstruct)) == NULL) 
perror ("QlgGetcwd() error"); 
else 
printf ("Successful change to new current working directory."); 
} 
} 
Output: 


Successful change to new current working directory. 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


QigGetPathFromFilelD()--Get Path Name of 
Object from Its File ID (using NLS-enabled path 
name) 


Syntax 


#include <Qp0lstdi.h> 


Qlg_Path_Name_T *QlgGetPathFromFileID(Qlg_Path_Name_T *buf, 
size_t size,Qp0Ol1FID_t fileid); 


Service Program Name: QPOLLIB2 


Default Public Authority: *USE 


Threadsafe: Yes 


The QlgGetPathFromFileIDQ function, like the Qp0IGetPathFromFileID() function, determines an 
absolute path name of the file identified by fileid and stores it in buf. The difference is that the 
QlgGetPathFromFileIDQ function points to a Qlg_Path_Name_T structure, while 
Qp01GetPathFromFileID(Q) points to a null-terminated character string. 


Limited information on the buf parameter is provided here. For more information on the buf parameter and 
for a discussion of other parameters, authorities required, return values, and related information, see 
Qp01GetPathFromFileIDQ--Get Path Name of Object from Its File ID. 


Parameters 


buf 
(Output) A pointer to a Qlg_Path_Name_T structure that will be used to hold an absolute path 
name or a pointer to an absolute path name of the file identified by fileid. The path name is not 
null-terminated within the structure. For more information on the Qlg_ Path_Name_T structure, see 
Path name format. 


size 
(Input) The number of bytes in the buffer buf. 
fileid 


(Input) The identifier of the file whose path name is to be returned. This identifier is logged in audit 
journal entries to identify the file being audited. See the Parent File ID and Object File ID fields of 


at 
the audit journal entries described in the iSeries Security Reference ~ book. 


Related Information 


© 01GetPathFromFileIDQ--Get Path Name of Object from Its File ID 


Example 


The following example determines the path name of a file, given its file ID. In this example, the fileid is 
hardcoded. More realistically, the fileid is obtained from the audit journal entry and passed to 
QlgGetPathFromFileID(. 


#include <Qp0lstdi.h> 
#include <stdio.h> 
#include <qtqiconv.h> 


void Path_Print (Qlg_Path_Name_T *); 


main () 
{ 
QpOl1lFID_t 
fileid = {0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, Ox00, 
0x00, Ox00, Ox00, Ox00, Ox80, OxFF, OxCF, 0x00}; 


const char US_const[3]= "US"; 
const char Language_const [4]="ENU",; 
typedef struct pnstruct 
{ 
Qlg_Path_Name_T qlg_struct; 
char pn[1024]; /* This size must be large enough */ 
/* to contain the path name. */ 


}; 
struct pnstruct path; 


[KKK KKK KK KK KK KK I KK KK KK KK / 


/* Initialize Qlg_Path_Name_T parameters */ 
[KKK KK KR KKK KK KK I KK KK KK KKK / 


memset ((void*) &path, 0x00, sizeof(struct pnstruct)); 
memcpy (path.gqlg_struct.Country_ID, US_const,2); 
memcpy (path.gqlg_struct.Language_ID, Language_const, 3); 


if (QlgGetPathFromFileID((Qlg_Path_Name_T *) &path, 
sizeof (struct pnstruct), fileid) == NULL) 
perror ("QlgGetPathFromFileID() error"); 
else 


{ 


printf ("Path retrieved successfully.\n"); 
Path_Print ((Qlg_Path_Name_T *) &path) ; 


} 
} 


void Path_Print (Qlg_Path_Name_T *path_to_print_pointer) 
{ 


[KKK KKK KK KK KK KK KE I I KK / 


/* Print a path name that is in the Qlg_Path_Name_T format. Re]: 
[KR KK KK KK KK KK II II I KK KK / 


#define PATH_TYPE POINTER 0x00000001 /* If flag is on, * / 
/* input structure contains a pointer */ 

/* to the path name, else the path */ 

/* name is in contiguous storage A: 

/* within the qlg structure. La 

typedef union pn_input_type /* Format of input path name. */ 


{ 
char pn_char_type[256]; /* in contiguous storage */ 
char *pn_ptr_type; /* a pointer * / 
}; 
typedef struct pnstruct 
{ 
Qlg_Path_Name_T qlg_struct; 
union pn_input_type pn; 
}; 
struct pnstruct *pns; 
char *path_ptr; 


size_t insz; 

size_t outsz = 1000; 
char outbuf[1000]; 
char *outbuf_ptr; 
iconv_t cd; 

size_t ret_iconv; 


/* Indicates to convert from ccsid 13488 to 37. * / 
QtqCode_T toCode = {37,0,0,0,0,0}; 
QtqCode_T fromCode = {13488,0,0,1,0,0}; 


if (path_to_print_pointer != NULL) 
{ 


[BRK KKK RK KK KK I I I RK KK KK / 


/* Point to and get the size of the path name. ee 

[RK KKK KK KK KK I EK RK KK KK / 

pns = (struct pnstruct *)path_to_print_pointer; 

if (path_to_print_pointer->Path_Type & PATH_TYPE_POINTER) 
path_ptr = pns->pn.pn_ptr_type; 

else path_ptr = (char *) (pns->pn.pn_char_type) ; 

insz = pns->qlg_struct.Path_Length; /* Get path length.*/ 


[BRK KKK RK KK KK I I I RK KK KK / 


/* Initialize the print buffer. Bad 
[BRK KKK RK KK KK I KI I I RK KK KK / 
outbuf_ptr = (char *)outbuf; 

memset (outbuf_ptr, 0x00, insz); 


[RK KKK RK KK KK I I I KK KK / 


/* Use iconv to convert the CCSID. ua 
[BRK KKK KK KK KK I I I I KR KK KK / 
cd = QtqIconvOpen (&toCode, 

&fromCode); /* Open a descriptor*/ 
if (cd.return_value == -1) 
{ perror("Open conversion descriptor error"); 


if (O != ((iconv(cd, 
(char **)&(path_ptr), 
&insz, 
(char **)&(outbuf_ptr), 
&0utsz)))) 

{ 


ret_iconv= iconv_close(cd);/* Close conversion descriptor*/ 
perror ("Conversion error"); 
return; 


} 


[RK KKK RK KR KK IK KR KK KK I RK KK KK / 


/* Print the name and close the conversion descriptior. * / 
[BKK KKK KK KKK KK KK RK KK KR KK OK / 


printf("The file's path is: %s\n",outbuf); 
ret_iconv = iconv_close(cd); 
} /* path_to_print_pointer != NULL */ 


} /* Path Print */ 


Output: 


Path retrieved successfully. 
The file's path is: /myfile 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


QlgGetpwnam()--Get User Information for User 
Name (using NLS-enabled path name) 


Syntax 


#include <pwd.h> 


struct qplg_passwd *QlgGetpwnam(const char *name); 


Service Program Name: QS YPAPI 


Default Public Authority: *USE 


Threadsafe: No 


The QlgGetpwnam() function returns a pointer to an object of type struct qplg_passwd containing an entry 
from the user database with a matching name. 


Parameters 


name 


(Input) User profile name. 


The struct qplg_passwd, which is defined in the pwd.h header file, has the following elements: 


char * pw_name User name 

uid_t pw_uid User ID 

uid_t pw_gid Group ID 
Qlg_Path_Name_T* pw_dir Initial working directory 
char * pw_shell Initial user program 


See getpwnam()--Get User Information for User Name for more on the parameter. 


Authorities 


*READ authority is required to the user profile associated with the name. 


Note: Adopted authority is not used. 


Return Value 


value 


QlgGetpwnam was successful. The return value points to static data that is overwritten on each 
call to this function. This static storage area is also used by the QlgGetpwuid() function. 


NULL pointer 


QlgGetpwnam was not successful. The errno global variable is set to indicate the error. 


Error Conditions 


If QlgGetpwnam() is not successful, errno usually indicates one of the following errors. Under some 
conditions, errno could indicate an error other than those listed here. 


[EAGAIN] 


The user profile associated with the name is currently locked by another process. 


[EC2] 


Detected pointer that is not valid. 


[EINVAL] 


Value is not valid. Check the job log for messages. 


[ENOENT] 


The user profile associated with the name was not found. 


[ENOMEM] 


The user profile associated with the U/D has exceeded its storage limit or is unable to allocate 
memory. 


[EPERM] 


The calling job does not have *READ authority to the user profile associated with the name. 
[EUNKNOWN] 
Unknown system state. Check the job log for a CPF9872 message. If there is no message, verify 
that the home directory field in the user profile can be displayed. 
Usage Notes 


The path name is returned in the default IFS UNICODE CCSID. 


Related Information 


e The <pwd.h> file (see Header Files for UNIX-Type APIs) 


e@ getpwnam()--Get User Information for User Name Qlg getpwnam_r 


e getpwnam_r()--Get User Information for User Name 


e QleGetpwnam_r()--Get User Information for User Name (using NLS-enabled path name) 


Example 


The following example gets the user database information for the user name of MYUSER. The UID is 22. 
The GID is 1012. The initial working directory is /home/MY USER. The initial user program is 
*LIBL/QCMD. 


#include <pwd.h> 


main () 


{ 
struct qplg_passwd *pd; 


if (NULL == (pd = QlgGetpwnam("MYUSER") ) ) 
perror("QlgGetpwnam() error."); 

else 

{ 
printf("The user name is: %s\n", pd->pw_name) ; 
printf("The user id is: %u\n", pd->pw_uid); 
printf("The group id is: %u\n", pd->pw_gid); 
printf("The initial working directory length is: %d\n", 

pd->pw_dir->Path_Length) ; 

printf("The initial working directory CCSID is : %d\n", 

pd->pw_dir->CCSID); 

printf("The initial user program is: %s\n", pd->pw_shell); 


} 
Output: 


The user name is: MYUSER 

The user id is: 22 

The group id is: 1012 

The initial working directory length is: 24 
The initial working directory CCSID is : 13488 
The initial user program is: *LIBL/QCMD 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


QigGetpwnam_r()--Get User Information for User 
Name (using NLS-enabled path name) 


Syntax 


#include <sys/types.h> 
#include <pwd.h> 


int QlgGetpwnam_r(const char *name, 
struct qplg_passwd *pwd, 
char *buffer, 
size_t bufsize, 
struct qplg_passwd **result); 


Service Program Name: QS YPAPI 


Default Public Authority: *USE 


Threadsafe: Yes 


The QlgGetpwnam_r() function updates the gplg_passwd structure pointed to by pwd and stores a pointer to 
that structure in the location pointed to by result. The structure contains an entry from the user database with a 
matching name. 


Parameters 


name 

(Input) A pointer to a user profile name. 
pwd 

(Input) A pointer to a qplg_passwd structure. 


buffer 


(Input) A pointer to a buffer from which memory is allocated to hold storage areas referenced by the 
structure pwd. 


bufsize 
(Input) The size of buffer in bytes. 

result 
(Input) A pointer to a location in which a pointer to the updated qplg_passwd structure is stored. If an 
error occurs or if the requested entry cannot be found, a NULL pointer is stored in this location. 


The struct qplg_passwd, which is defined in the pwd.h header file, has the following elements: 


char * pw_name User name 

uid_t pw_uid User ID 

uid_t pw_gid Group ID 
Qlg_Path_Name_T* pw_dir Initial working directory 


char * pw_shell Initial user program 


See getpwnam_r()--Get User Information for User Name for more on the pwd, result and other parameters. 


Authorities 


*READ authority is required to the user profile associated with the name. 


Return Value 


0 


QlgGetpwnam_r was successful. 


Any other value 


Failure: The return value contains an error number indicating the error. 


Error Conditions 


If QlgGetpwnam_r() is not successful, the return value usually indicates one of the following errors. Under 
some conditions, the value could indicate an error other than those listed here. 


[EAGAIN] 


The user profile associated with the name is currently locked by another process. 


[EC2] 
Detected pointer that is not valid. 


[EINVAL] 


Value is not valid. Check the job log for messages. 


[ENOENT] 


The user profile associated with the name was not found. 


[ENOMEM] 


The user profile associated with the UJD has exceeded its storage limit or is unable to allocate 
memory. 


[EPERM] 
The calling job does not have *READ authority to the user profile associated with the name. 


[ERANGE] 


Insufficient storage was supplied through buffer and bufsize to contain the data to be referenced by the 
resulting group structure. 


[EUNKNOWN] 
Unknown system state. Check the job log for a CPF9872 message. If there is no message, verify that 


the home directory field in the user profile can be displayed. 


Usage Notes 


The path name is returned in the default IFS UNICODE CCSID. 


Related Information 


e The <pwd.h> file (see Header Files for UNIX-Type APIs) 


e@ getpwnam()--Get User Information for User Name 


e@ getpwnam_r()--Get User Information for User Name 


e QlgGetpwnam()--Get User Information for User Name (using NLS-enabled path name) 


Example 


The following example gets the user database information for the user name of MYUSER. The uid is 22. The 
gid is 1012. The initial working directory is /home/MYUSER. The initial user program is *LIBL/QCMD. 


#include <sys/types.h> 
#include <pwd.h> 
#include <stdio.h> 
#include <errno.h> 


main () 
{ 
struct qplg_passwd pd; 
gplg_passwd ** tempPwdPtr; 
char pwdbuffer[200]; 
int pwdlinelen = sizeof (pwdbuffer) ; 


if ((QlgGetpwnam_r("MYUSER", &pd, pwdbuffer, pwdlinelen, tempPwdPtr) ) !=0 


perror("QlgGetpwnam_r() error."); 
else 
{ 
printf("\nThe user name is: %s\n", pd->pw_name) ; 
printf("The user id is: %u\n", pd->pw_uid); 
printf("The group id is: %u\n", pd->pw_gid); 
printf("The initial working directory length is: %d\n", 
pd->pw_dir->Path_Length) ; 
printf("The initial working directory CCSID is : %d\n", 
pd->pw_dir->CCSID); 
printf("The initial user program is: %s\n", pd->pw_shell); 


} 


Output: 


The user name is: MYUSER 


) 


The user id is: 22 

The group id is: 0 

The intial working directory length is: 24 
The intial working directory CCSID is : 13488 
The initial user program is: *LIBL/QCMD 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


QlgGetpwuid()--Get User Information for User 
ID (using NLS-enabled path name) 


Syntax 


#include <pwd.h> 


struct gqplg_passwd *QlgGetpwuid(uid_t uid); 
Service Program Name: QS YPAPI 


Default Public Authority: *USE 


Threadsafe: No 


The QlgGetpwuid() function returns a pointer to an object of type struct qplg_passwd containing an entry 
from the user database with a matching user ID (UID). 


Parameters 


UID 
(Input) User ID. 


The struct qplg_passwd, which is defined in the pwd.h header file, has the following elements: 


char * pw_name User name 

uid_t pw_uid User ID 

uid_t pw_gid Group ID 
Qlg_Path_Name_T* pw_dir Initial working directory 
char * pw_shell Initial user program 


See getpwuid()--Get User Information for User ID for more on the parameter. 


Authorities 


*READ authority is required to the user profile associated with the UJD. 


Note: Adopted authority is not used. 


Return Value 


value 


QlgGetpwuid() was successful. The return value points to static data that is overwritten on each 
call to this function. This static storage area is also used by the QlgGetpwnam() function. 


NULL pointer 


QlgGetpwuid() was not successful. The errno global variable is set to indicate the error. 


Error Conditions 


If QlgGetpwuid() is not successful, errno usually indicates one of the following errors. Under some 
conditions, errno could indicate an error other than those listed here. 


[EAGAIN] 


The user profile associated with the wid is currently locked by another process. 


[EC2] 


Detected pointer that is not valid. 


[EINVAL] 


Value is not valid. Check the job log for messages. 


[ENOENT] 


The user profile associated with UID was not found. 


[ENOMEM] 


The user profile associated with the UJD has exceeded its storage limit or is unable to allocate 
memory. 


[ENOSPC] 


Machine storage limit exceeded. 


[EPERM] 
The calling job does not have *READ authority to the user profile associated with the UID. 


[EUNKNOWN] 


Unknown system state. Check the job log for a CPF9872 message. If there is no message, verify 
that the home directory field in the user profile can be displayed. 


Usage Notes 


Th path name is returned in the default IES UNICODE CCSID 


Related Information 


e The <pwd.h> file (see Header Files for UNIX-Type Functions) 


e@ getpwuidQ--Get User Information for User ID 


e@ getpwuid_r()--Get User Information for User ID 


e QleGetpwuid_r()--Get User Information for User ID (using NLS-enabled path name) 


Example 


The following example gets the user database information for the uid of 22. The user name is MYUSER. 
The gid is 1012. The initial working directory is /home/MYUSER. The initial user program is 
*LIBL/QCMD. 


#include <pwd.h> 


main () 


{ 
struct qplg_passwd *pd; 


if (NULL == (pd = QlgGetpwuid(22))) 
perror("QlgGetpwuid() error."); 

else 

{ 
printf("The user name is: %s\n", pd->pw_name) ; 
printf("The user id is: %u\n", pd->pw_uid); 
printf("The group id is: %u\n", pd->pw_gid); 
printf("The initial working directory length is: %d\n", 


pd->pw_dir->Path_Length) ; 

printf("The initial working directory CCSID is : %d\n", 
pd->pw_dir->CCSID); 

printf("The initial user program is: %s\n", pd->pw_shell); 


The user name is: MYUSER 

The user id is: 22 

The group id is: 1012 

The intial working directory length is: 24 
The intial working directory CCSID is : 13488 
The initial user program is: *LIBL/QCMD 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


QigGetpwuid_r()--Get User Information for User 
ID (using NLS-enabled path name) 


Syntax 


#include <sys/types.h> 
#include <pwd.h> 


int QlgGetpwuid_r(uid_t uid, 
struct qplg_passwd *pwd, 
char *buffer, 
size_t bufsize, 
struct gqplg_passwd **result); 


Service Program Name: QS YPAPI 


Default Public Authority: *USE 


Threadsafe: Yes 


The QlgGetpwuid_r() function updates the gplg_passwd structure pointed to by pwd and stores a pointer 
to that structure in the location pointed to by result. The structure contains an entry from the user database 
with a matching UID. 


Parameters 


UID 

(Input) A pointer to a user ID. 
pwd 

(Input) A pointer to a struct qplg_passwd. 
buffer 


(Input) A pointer to a buffer from which memory is allocated to hold storage areas referenced by 
the structure qplg_passwd. 


bufsize 
(Input) The size of buffer in bytes. 
result 
(Input) A pointer to a location in which a pointer to the updated qplg_passwd structure is stored. If 


an error occurs or if the requested entry cannot be found, a NULL pointer is stored in this location. 


The struct qplg_passwd, which is defined in the pwd.h header file, has the following elements: 


char * pw_name User name 

uid_t pw_uid User ID 

uid_t pw_gid Group ID 
Qlg_Path_Name_T pw_dir Initial working directory 


char * pw_shell Initial user program 


See getpwuid_r(Q)--Get User Information for User ID for more on the pwd, result and other parameters. 


Authorities 


*READ authority is required to the user profile associated with the UJD. 


Return Value 


0 
QlgGetpwuid_r() was successful. 


Any other value 


Failure: The return value contains an error number indicating the error. 


Error Conditions 


If QlgGetpwuid_r() is not successful, the error value usually indicates one of the following errors. Under 
some conditions, the value could indicate an error other than those listed here. 


[EAGAIN] 


The user profile associated with the wid is currently locked by another process. 


[EC2] 


Detected pointer that is not valid. 


[EINVAL] 


Value is not valid. Check the job log for messages. 


[ENOENT] 


The user profile associated with uid was not found. 


[ENOMEM] 


The user profile associated with the UID has exceeded its storage limit or is unable to allocate 
memory. 


[ENOSPC] 


Machine storage limit exceeded. 


[EPERM] 
The calling job does not have *READ authority to the user profile associated with the UID. 


[ERANGE] 


Insufficient storage was supplied using buffer and bufsize to contain the data to be referenced by the 
resulting group structure. 


[EUNKNOWN] 


Unknown system state. Check the job log for a CPF9872 message. If there is no message, verify 
that the home directory field in the user profile can be displayed. 


Usage Notes 


The path name is returned in the default IFS UNICODE CCSID. 


Related Information 


e The <pwd.h> file (see Header Files for UNIX-Type Functions) 


@ getpwuid(--Get User Information for User ID 


e@ getpwuid_r()--Get User Information for User ID 


e QlgGetpwuid()--Get User Information for User ID (using NLS-enabled path name) 


Example 


The following example gets the user database information for the uid of 22. The user name is MYUSER. 
The GID is 1012. The intial working directory is /home/MYUSER. The initial user program is 
*LIBL/QCMD. 


#include <sys/types.h> 
#include <pwd.h> 
#include <stdio.h> 
#include <errno.h> 


main () 

{ 
struct qplg_passwd pd; 
passwd ** tempPwdPtr; 
char pwdbuffer[200]; 


int pwdlinelen = sizeof (pwdbuffer); 
if ((QlgGetpwuid_r (22, &pd, pwdbuffer, pwdlinelen,tempPwdPtr) ) !=0) 
perror("QlgGetpwuid_r() error."); 
else 
{ 
printf("\nThe user name is: %s\n", pd->pw_name) ; 
printf("The user id is: %u\n", pd->pw_uid); 
printf("The group id is: %u\n", pd->pw_gid); 
printf("The initial working directory length is: %d\n", 


pd->pw_dir->Path_Length) ; 
printf("The initial working directory CCSID is : %d\n", 


pd->pw_dir->CCSID); 
printf("The initial user program is: %s\n", pd->pw_shell); 


} 
Output: 


The user name is: MYUSER 

The user ID is: 22 

The group ID is: 0 

The initial working directory length is: 24 
The initial working directory CCSID is : 13488 
The initial user program is: *LIBL/QCMD 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


QlgLchown()--Change Owner and Group of 
Symbolic Link (using NLS-enabled path name) 


Syntax 


#include <unistd.h> 


int QlgLchown(Qlg_Path_Name_T *path, uid_t owner,gid_t 
group) ; 


Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgLchown() function, like the Ichown() function, changes the owner and group of a file. The 
difference is that the QlgLchown() function takes a pointer to a Qlg_Path_Name_T structure, while 
Ichown() takes a pointer to a character string. 


Limited information on the path parameter is provided here. For more on the path parameter and for a 
discussion of other parameters, authorities required, return values, and related information, see 
Ichown()--Change Owner and Group of Symbolic Link. 


Parameters 


path 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path 
name of the file whose owner and group are being changed. For more information on the 
Qlg_ Path_Name_T structure, see Path name format. 


Related Information 


e IchownQ--Change Owner and Group of Symbolic Link 
e QlgChmod()--Change File Authorizations 
e QleLstat()--Get File or Link Information 


e OlgStat(--Get File Information 


Example 
The following example changes the owner and group of a file: 


#include <stdio.h> 
#include <unistd.h> 
#include <sys/stat.h> 
#include <sys/types.h> 
#include <Qp0lstdi.h> 


main() { 


#define mypath_link_name "temp.link" 
#define mypath_fn "temp.file" 


const char US_const]3[= "US"; 
const char Language_const]4[="ENU",; 


struct stat info; 
typedef struct pnstruct 
{ 
Qlg_Path_Name_T qlg_struct; 
char pn]100[; /* This array size must be >= the */ 
/* length of the path name or this must */ 
/* be a pointer to the path name. a, 


}; 
struct pnstruct path_link; 
struct pnstruct path_fn; 


[BR KK KKK KK KK KK KI I KI I I KK KKK / 


h® Initialize Qlg_Path_Name_T parameters ay 
[RR KK KK KK KK KK KI I I I KK KK / 
memset ((void*) &path_link, 0x00, sizeof(struct pnstruct)); 
path_link.gqlg_struct.CCSID = 37; 
memcpy (path_link.qlg_struct.Country_ID,US_const, 2); 
memcpy (path_link.qlg_struct.Language_ID, Language_const,3); 
path_link.gqlg_struct.Path_Type = QLG_CHAR_SINGLE; 
path_link.gqlg_struct.Path_Length = sizeof (mypath_link_name)-1; 
path_link.glg_struct.Path_Name_Delimiter]0O[ = '/'; 
memcpy (path_link.pn,mypath_link_name, sizeof (mypath_link_name)-1); 


memset ((void*) &path_fn, 0x00, sizeof (struct pnstruct)); 
path_fn.gqlg_struct.CCSID = 37; 

memcpy (path_fn.qlg_struct.Country_ID,US_const, 2); 

memcpy (path_fn.qlg_struct.Language_ID, Language_const,3)j; 
path_fn.gqlg_struct.Path_Type = QLG_CHAR_SINGLE; 
path_fn.gqlg_struct.Path_Length = sizeof (mypath_fn)-1; 
path_fn.gqlg_struct.Path_Name_Delimiter]O[ = '/'; 

memcpy (path_fn.pn,mypath_fn, sizeof (mypath_fn)-1); 


if (QlgSymlink ((Qlg_Path_Name_T *) &path_fn, 
(Qlg_Path_Name_T *)&path_link) == -1) 
perror ("QlgSymlink() error"); 
else { 
QlgLstat ((Qlg_Path_Name_T *) é&path_link, é&info); 
printf ("original owner was %d and group was %d\n", info.st_uid, 


info.st_gid); 


if (QlgLchown((Qlg_Path_Name_T *)&path_link, 152, 0) != 0) 
perror ("QlgLchown() error"); 
else { 


QlgLstat ((Qlg_Path_Name_T *) épath_link, é&info); 
printf ("after QlgLchown(), owner is %d and group is %d\n", 
info.st_uid, info.st_gid); 


} 
QlgUnlink((Qlg_Path_Name_T *) &path_link); 


Output: 


original owner was 137 and group was 0 
after QlgLchown(), owner is 152 and group is 0 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


QlgLink()--Create Link to File (using 
NLS-enabled path name) 


Syntax 


#include <unistd.h> 


int QlgLink(Qlg_Path_Name_T *existing, Qlg_Path_Name_T *new); 
Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgLink() function, like the link() function, provides an alternative path name for the existing file so that 
the file can be accessed by either the existing name or the new name. The difference is that the QlgLink() 
function supports pointers to Qlg_Path_Name_T structures, while link() supports pointers to character strings. 


Limited information on the existing and the new parameters is provided here. For more information on these 
parameters and for a discussion of the authorities required, return values, and related information, see 
linkQ--Create Link to File. 


Parameters 


existing 
(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path 


name of an existing file to which a new link is to be created. For more information on the 
Qlg_ Path_Name_T structure, see Path name format. 


new 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path 
name that is the name of the new link. For more information on the Qlg_Path_Name_T structure, see 
Path name format. 


Related Information 


e@ linkQ--Create Link to File 


e@ Qp0lUnlinkQ--Remove Link to File (using NLS-enabled path name) 


Example 
The following example uses QlgLink(): 


#include <stdio.h> 
#include <unistd.h> 
#include <sys/types.h> 
#include <sys/stat.h> 
#include <fcntl.h> 
#include <stdlib.h> 
#include <Qp0lstdi.h> 


main () 
{ 
int file_descriptor; 
struct stat info; 
#define mypath_fn "link.example.file" 
#define mypath_In "link.example.link" 


const char US_const[3]= "US"; 
const char Language_const[4] ="ENU"; 
typedef struct pnstruct 
{ 
Qlg_Path_Name_T gqlg_struct; 
char pn[100]; /* This array size must be >= the */ 
/* length of the path name or must */ 
/* be a pointer to the path name. */ 


}; 
struct pnstruct path_fn; 
struct pnstruct path_ln; 


[ORK KKK KK KK KK KKK KR RR KK KK KK / 


/* Initialize Qlg_Path_Name_T parameters ad 
[BORK KKK KK KK RK KK KK RK KR RK KK RK RK KK / 
memset ((void*)&path_fn, 0x00, sizeof(struct pnstruct)); 
path_fn.qlg_struct.CCSID = 37; 
memcpy (path_fn.glg_struct.Country_ID,US_const,2); 
memcpy (path_fn.glg_struct.Language_ID, Language_const, 3); 
path_fn.glg_struct.Path_Type = QLG_CHAR_SINGLE; 
path_fn.qlg_struct.Path_Length = sizeof (mypath_fn)-1; 
path_fn.qlg_struct.Path_Name_Delimiter[0] = '/'; 
memcpy (path_fn.pn,mypath_fn, sizeof (mypath_fn)-1); 


memset ((void*)&path_ln, 0x00, sizeof(struct pnstruct)); 
path_ln.qlg_struct.CCSID = 37; 

memcpy (path_In.glg_struct.Country_ID,US_const,2); 

memcpy (path_In.glg_struct.Language_ID, Language_const, 3); 
path_In.glg_struct.Path_Type = QLG_CHAR_SINGLE; 
path_In.qlg_struct.Path_Length = sizeof (mypath_Il1n)-1; 
path_ln.gqlg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (path_ln.pn,mypath_lin, sizeof (mypath_ln)-1); 


if ((file_descriptor = QlgCreat ((Qlg_Path_Name_T *)&path_fn, S_IWUSR)) < 
0) 
perror("QlgCreat() error"); 
else { 
close (file_descriptor); 


puts ("before QlgLink()"); 
QlgStat ((Qlg_Path_Name_T *) &path_fn, &info) ; 


printf (" number of links is Shu\n",info.st_nlink); 
if (QlgLink((Qlg_Path_Name_T *) &path_fn, 
(Qlg_Path_Name_T *)&path_ln) != 0) { 


perror("QlgLink() error"); 
QlgUnlink ((Qlg_Path_Name_T *) &path_fn); 
} 


else { 
puts("after QlgLink()"); 
QlgStat ((Qlg_Path_Name_T *) &path_fn, &info); 
printf (" number of links is Shu\n",info.st_nlink); 
QlgUnlink ((Qlg_Path_Name_T *) &path_ln); 
puts("after first QlgUnlink()"); 
QlgLstat ((Qlg_Path_Name_T *) &path_fn, &info); 
printf (" number of links is Shu\n",info.st_nlink); 


QlgUnlink ((Qlg_Path_Name_T *) &path_fn)j; 


} 


Output: 


before QlgLink () 

number of links is 1 
after QlgLink () 

number of links is 2 
after first QlgUnlink () 

number of links is 1 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


QlgLstat()--Get File or Link Information (using 
NLS-enabled path name) 


Syntax 


#include <sys/stat.h> 


int QlgLstat (Qlg_Path_Name_T *path,struct stat *buf); 
Service Program Name: QPOLLIB1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgLstat() function, like the IstatQ function, gets status information about a specified file and places it in 
the area of memory pointed to by buf. The difference is that the QlgLstat() function takes a pointer to a 
Qlg_ Path_Name_T structure, while Istat() takes a pointer to a character string. 


Limited information on the path parameter is provided here. For more information on the path parameter and for 
a discussion of other parameters, authorities required, return values, and related information, see Istat()--Get File 


or Link Information. 


Parameters 


path 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path name 
of the file. For more information on the Qlg_Path_Name_T structure, see Path name format. 


Related Information 


e |stat()--Get File or Link Information 

e@ QlgChmod()--Change File Authorizations (using NLS-enabled path name) 

e@ QlgChown()--Change Owner and Group of File (using NLS-enabled path name) 
e@ QlgCreat()--Create or Rewrite File (using NLS-enabled path name) 

e@ QlgLink()--Create Link to File (using NLS-enabled path name) 

e@ QlgMkdirQ--Make Directory (using NLS-enabled path name) 

e@ QlgReadlinkQ--Read Value of Symbolic Link (using NLS-enabled path name) 
e@ QlgStatQ--Get File Information (using NLS-enabled path name) 

e@ QlgSymlinkQ--Make Symbolic Link (using NLS-enabled path name) 

e@ QlgUtime(Q--Set File Access and Modification Times (using NLS-enabled path name) 
e@ Qp0lUnlink(Q--Remove Link to File (using NLS-enabled path name) 


Example 


The following example provides status information for a file: 


#include <sys/types.h> 
#include <sys/stat.h> 
#include <stdio.h> 
#include <fcntl.h> 
#include <unistd.h> 
#include <time.h> 
#include <stdio.h> 
#include <QpOlstdi.h> 


main() { 


struct stat info; 

int file_descriptor; 

#define mypath_fn "temp.file" 
#define mypath_ln "temp.link" 


const char US_const[3]= "US"; 
const char Language_const[4] ="ENU"; 
typedef struct pnstruct 
{ 
Qlg_Path_Name_T gqlg_struct; 
char pn[100]; /* This array size must be >= the */ 
/* length of the path name or this must */ 
/* be a pointer to the path name. say 


sd 
struct pnstruct path_fn; 
struct pnstruct path_ln; 


[BOK KK KK KK KK AK A AAA KK / 


/* Initialize Qlg_Path_Name_T parameters * / 
[ROK RK KKK KK KK A A A A A I  / 
memset ((void*) &path_fn, 0x00, sizeof(struct pnstruct)); 
path_fn.qlg_struct.CCSID = 37; 
memcpy (path_fn.qlg_struct.Country_ID,US_const,2); 
memcpy (path_fn.qlg_struct.Language_ID, Language_const, 3); 
path_fn.qlg_struct.Path_Type = QLG_CHAR_SINGLE; 
path_fn.qlg_struct.Path_Length = sizeof (mypath_fn)-1; 
path_fn.qlg_struct.Path_Name_Delimiter[0] = '/'; 
memcpy (path_fn.pn,mypath_fn, sizeof (mypath_fn)-1); 


memset ((void*) &path_In, 0x00, sizeof(struct pnstruct)); 
path_ln.qlg_struct.CCSID = 37; 

memcpy (path_In.qlg_struct.Country_ID,US_const,2); 

memcpy (path_In.qlg_struct.Language_ID, Language_const, 3); 
path_ln.qlg_struct.Path_Type = QLG_CHAR_SINGLE; 
path_ln.qlg_struct.Path_Length = sizeof (mypath_ln)-1; 
path_ln.qlg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (path_ln.pn,mypath_ln, sizeof (mypath_ln)-1); 


if ((file_descriptor = QlgCreat ((Qlg_Path_Name_T *)&path_fn, S_IWUSR)) < 0) 
perror("QlgCreat() error"); 

else { 
close (file_descriptor) ; 
if (QlgLink((Qlg_Path_Name_T *) &path_fn, 


(Qlg_Path_Name_T *) &path_ln) 


!=0 
perror("QlgLink() error"); 
else { 

if (QlgLstat ((Qlg_Path_Name_T *)&path_ln, &info) != 0) 
perror("QlgLstat() error"); 

else { 
puts ("OQlgLstat() returned:"); 
printf(" inode: Sda\n", (int) info.st_ino); 
printf(" dev id: Sda\n", (int) info.st_dev); 
printf (" mode: 308x\n", info.st_mode); 
printf(" links: Sda\n", info.st_nlink); 
printf (" uid: Sda\n", (int) info.st_uid); 
printf (" gid: Sda\n", (int) info.st_gid); 


} 
QlgUnlink((Qlg_Path_Name_T *) &path_ln); 
} 
QlgUnlink ((Qlg_Path_Name_T *) &path_fn); 
} 


Output: 


QlgLstat() returned: 


inode: 8477 
dev id: 0 
mode: 00008080 
links: 2 
uid: 1782 
gid: 0 
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QlgLstat64()--Get File or Link Information (large 
file enabled and using NLS-enabled path name) 


Syntax 


#include <sys/stat.h> 


int QlgLstat64(Qlg_Path_Name_T *path, struct stat64 *buf); 
Service Program Name: QPOLLIB1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgLstat64() function, like the Istat64Q function, gets status information about a specified file and places it 
in the area of memory pointed to by buf. The difference is that the QlgLstat64() function takes a pointer to a 
Qlg_ Path_Name_T structure, while Istat64() takes a pointer to a character string. 


Limited information on the path parameter is provided here. For more information on the path parameter and for 
a discussion of other parameters, authorities required, return values, and related information, see Istat64()--Get 


File or Link Information (Large File Enabled) or Istat()--Get File or Link Information. 


Parameters 


path 


(Input) A pointer to a Qlg_ Path_Name_T structure that contains a path name or a pointer to a path name 
of the file. For more information on the Qlg_Path_Name_T structure, see Path name format. 


Related Information 


e |stat64(--Get File or Link Information (large file enabled and using NLS-enabled path name) 
e |statQ--Get File or Link Information (using NLS-enabled path name) 

e@ QlgChmod()--Change File Authorizations (using NLS-enabled path name) 

e@ QlgChown()--Change Owner and Group of File (using NLS-enabled path name) 

e@ QlgCreat()--Create or Rewrite File (using NLS-enabled path name) 

e@ QlgLink(--Create Link to File (using NLS-enabled path name) 

e@ QlgMkdirQ--Make Directory (using NLS-enabled path name) 

e@ QlgReadlinkQ--Read Value of Symbolic Link (using NLS-enabled path name) 

@ QlgStatQ--Get File Information (using NLS-enabled path name) 

e@ QlgSymlinkQ--Make Symbolic Link (using NLS-enabled path name) 

e@ QlgUtime(Q--Set File Access and Modification Times (using NLS-enabled path name) 
e@ Qp0lUnlink(Q)--Remove Link to File (using NLS-enabled path name) 


Example 


The following example provides status information for a file: 


#define 

#include 
#include 
#include 
#include 
#include 
#include 
#include 


main() { 
struct 


LARGE _ FILE API 


<sys/types.h> 
<sys/stat.h> 
<stdio.h> 
<fentl.h> 
<unistd.h> 
<time.h> 
<QpOlstdi.h> 


stat64 info; 


int file_descriptor; 
#define mypath_fn "temp.file" 
#define mypath_In "temp.link" 


const char US_const [3]= 
const char Language_const [4] 


typedef struct pnstruct 


{ 


Qlg_Path_Name_T gqlg_struct; 


char pn[100]; 


}; 
struct 
struct 


pnstruct path_fn; 
pnstruct path_ln; 


WSN 


/* This array size must be >= 
/* length of the path name or must */ 
/* be a pointer to the path name. 


[OK KK KK KK KK A I A AAA I  / 


/* 


Initialize Qlg_Path_Name_T parameters 


xf 


[OK KK KK KK KK A KK A A AA A / 


memset ((void*) &path_fn, 


path_fn.qlg_struct.CCSID = 


memcpy (path_fn.qlg_struct.Country_ID,US_const,2); 

memcpy (path_fn.qlg_struct.Language_ID, Language_const, 3); 
path_fn.qlg_struct.Path_Type 
path_fn.qlg_struct.Path_Length 
path_fn.qlg_struct.Path_Name_Delimiter[0] 
memcpy (path_fn.pn,mypath_fn, sizeof (mypath_fn)-—); 


memset ((void*) &path_in, 


path_ln.qlg_struct.CCSID = 


memcpy (path_In.qlg_struct.Country_ID,US_const,2); 

memcpy (path_lIn.qlg_struct.Language_ID, Language_const, 3); 
path_ln.qlg_struct.Path_Type 
path_ln.qlg_struct.Path_Length 
path_ln.qlg_struct.Path_Name_Delimiter[0] 
memcpy (path_lIn.pn,mypath_ln, sizeof (mypath_l1n)-); 


if ((file_descriptor = QlgCreat64((Qlg_Path_Name_T *)&path_fn, 
perror ("OQlgCreat 64 () 


else { 


close(file_descriptor) ; 


if (QlgLink((Qlg_Path_Name_T *) &path_fn, 


0x00, sizeof (struct pnstruct)); 


QLG _CHAR_SINGLE; 
sizeof (mypath_fn)-1; 


0x00, 


sizeof (struct pnstruct)); 


QLG _CHAR_SINGLE; 
sizeof (mypath_ln)-1; 


error"); 


S_IWUSR) ) 


< 


(Qlg_Path_Name_T *)&path_ln) != 0) 


perror("QlgLink() error"); 
else { 

if (QlgLstat64((Qlg_Path_Name_T *)&path_lin, &info) != 0) 
perror("QlgLstat64() error"); 

else { 
puts ("OQlgLstat64() returned:"); 
printf(" inode: Sda\n", (int) info.st_ino); 
printf(" dev id: Sda\n", (int) info.st_dev); 
printf (" mode: 308x\n", info.st_mode); 
printf(" links: Sda\n", info.st_nlink); 
printf (" uid: Sda\n", (int) info.st_uid); 
printf (" gid: sda\n", (int) info.st_gid)j; 
printf (" size: Slld\n", (long long) info.st_size); 


} 


QlgUnlink((Qlg_Path_Name_T *) &path_ln); 


} 


QlgUnlink ((Qlg_Path_Name_T *) &path_fn); 


} 
} 


Output: 


QlgLstat() returned: 


inode: 
dev id: 
mode: 
links: 
uid: 
gid: 
size: 


258 

1 
00008080 
2 

13° 

500 

18 
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QigMkdir()--Make Directory (using NLS-enabled 
path name) 


Syntax 


#include <sys/stat.h> 


int QlgMkdir(Qlg_Path_Name_T *path, mode_t mode); 


Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgMkdir( function, like the mkdir() function, creates a new, empty directory whose name is defined 
by path. The difference is that the QlgMkdir() function takes a pointer to a Qlg_Path_Name_T structure, 
while mkdir() takes a pointer to a character string. 


Limited information on the path parameter is provided here. For more information on the path parameter 
and for a discussion of other parameters, authorities required, return values, and related information, see 
mkdir()--Make Directory. 


Parameters 


path 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path 
name of the directory to be created. For more information on the Qlg_Path_Name_T structure, see 
Path name format. 


Related Information 


e mkdir()--Make Directory 

e QlgChmod()--Change File Authorizations (using NLS-enabled path name) 

e QlgStatQ--Get File Information (using NLS-enabled path name) 

e QlgPathconf()--Get Configurable Path Name Variables (using NLS-enabled path name) 


Example 
The following example creates a new directory: 


#include <sys/stat.h> 


#include <unistd.h> 
#include <stdio.h> 
main() { 


#define mypath "new_dir" 


const char US_const[3]= "US"; 
const char Language_const[4] ="ENU"; 
const char mypath_DOT_DOT[3] = ".."; 


typedef struct pnstruct 
{ 
Qlg_Path_Name_T qlg_struct; 
char pn[100]; /* This array size must be >= the */ 
/* length of the path name or this must */ 
/* be a pointer to the path name. * / 


}; 
struct pnstruct path; 
struct pnstruct path_DOT_DOT; 


[KK KK KKK KK KK KK I I I KK KKK / 


fos Initialize Qlg_Path_Name_T parameters xp 
[RK KK KK RK KK KK KK I IE I I KK KK / 


memset ((void*) &path, 0x00, sizeof(struct pnstruct)); 
path.glg_struct.CCSID = 37; 

memcpy (path.gqlg_struct.Country_ID, US_const,2); 

memcpy (path.gqlg_struct.Language_ID, Language_const, 3); 
path.glg_struct.Path_Type = QLG_CHAR_SINGLE; 
path.gqlg_struct.Path_Length = sizeof (mypath)-1; 
path.gqlg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (path.pn,mypath, sizeof (mypath) -1); 


memset ((void*) &path_DOT_DOT, 0x00, sizeof(struct pnstruct)); 
path_DOT_DOT.glg_struct.CCSID = 37; 

memcpy (path_DOT_DOT.glg_struct.Country_ID, US_const,2); 

memcpy (path_DOT_DOT.gqlg_struct.Language_ID, Language_const, 3); 
path_DOT_DOT.glg_struct.Path_Type = QLG_CHAR_SINGLE; 
path_DOT_DOT.qlg_struct.Path_Length = sizeof (mypath_DOT_DOT) -1; 
path_DOT_DOT.qlg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (path_DOT_DOT.pn,mypath_DOT_DOT, sizeof (mypath_DOT_DOT)-1); 


if (QlgMkdir((Qlg_Path_Name_T *) &path, 


S_IRWXU|S_IRGRP|S_IXGRP) != 0) 
perror ("QlgMkdir() error"); 
else if (QlgChdir((Qlg_Path_Name_T *)&path) != 0) 
perror ("first QlgChdir() error"); 
else if (QlgChdir((Qlg_Path_Name_T *)&path_DOT_DOT) != 0) 
perror ("second QlgChdir() error"); 
else if (QlgRmdir((Qlg_Path_Name_T *)&path) != 0) 
perror ("QlgRmdir() error"); 
else 
puts ("success!"); 


} 


API introduced: V5R1 
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QIgMkfifo()--Make FIFO Special File (using 
NLS-enabled path name) 


Syntax 


#include <sys/types.h> 
#include <sys/stat.h> 
#include <Qlg.h> 


int QlgMkfifo(const Qlg_Path_Name_T *path, 
mode_t mode); 


Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgMkfifoQ function, like the mkfifo() function, creates a new FIFO special file whose name is 
defined by path. The difference is that the QlgMkfifo() function takes a pointer to a Qlg_Path_Name_T 
structure, while mkfifo() takes a pointer to a character string. 


Limited information on the path parameter is provided here. For more information on the path parameter 
and for a discussion of other parameters, authorities required, return values, and related information, see 
mkfifo()--Make FIFO Special File. 


Parameters 
path 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path 
name of the FIFO to be created. For more information on the Qlg_Path_Name_T structure, see Path 


name format. 


Related Information 


e mkfifoQ--Make FIFO Special File 
e QlgChmod()--Change File Authorizations (using NLS-enabled path name) 


e QlgStatQ--Get File Information (using NLS-enabled path name) 


Example 


The following example creates a new FIFO: 


#include <sys/stat.h> 
#include <stdio.h> 
#include <string.h> 
#include <Qlg.h> 


void main () 
{ 
typedef struct pnstruct 
{ 
Qlg_Path_Name_T qlg_struct; 
char[100] pn; /* This size must be >= the path */ 
/* name length or a pointer to La 
/* the path name. * / 


}; 
struct pnstruct path; 


char *mypath = "/newFIFO"; 


[BR KKK KK KR KK KK KK EE I I KI KE KK KK / 


[* Initialize Qlg_Path_Name_T structure. */ 
[KR KKK KR KK KKK I I KK KK / 
memset ((void*)path name, 0x00, sizeof(struct pnstruct)); 
path.qlg_struct.CCSID = 37; 

memcpy (path.gqlg_struct.Country_ID, "US", 2); 

memcpy (path.gqlg_struct.Language_ID, "ENU", 3); 
path.qlg_struct.Path_Type = QLG_CHAR_SINGLE; 
path.qlg_struct.Path_Length = strlen(mypath); 
path.qlg_struct.Path_Name_Delimiter = '/'; 
memcpy (path.pn, mypath, strlen(mypath)); 


if (QlgMkfifo((Qlg_Path_Name_T *)path name, 


S_IRWxXU|S_IRWXO) != 0) 
perror ("QlgMkfifo() error"); 
else 
puts ("success!"); 
return; 


} 
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QligOpen()--Open a File (using NLS-enabled 
path name) 


Syntax 


#include <fcntl.h> 
#include <stdio.h> 
#include <Qp0lstdi.h> 


int QlgOpen(Qlg_Path_Name_T *Path_Name, 
int oflag, .. .); 


Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes for open() API. 


The QlgOpen() function, like the open() function, opens a file or creates a new, empty file whose name is 
defined by path and returns a number called a file descriptor. The difference is that the QlgOpen() 
function takes a pointer to a Qlg_Path_Name_T structure, while open() takes a pointer to a character string. 


Limited information on the path parameter is provided here. For more information on the path parameter 
and for a discussion of other parameters, authorities required, usage notes, return values, and related 
information, see open()--Open a File. 


Parameters 


path 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path 
name of the file to be opened. For more information on the Qlg_Path_Name_T structure, see Path 


name format. 


Related Information 
@ open()--Open a File 
e QlgCreat()--Create or Rewrite File (using NLS-enabled path name) 
e@ QlgOpen64()--Open File (large file enabled and using NLS-enabled path name) 


e QlgStatQ>--Get File Information (using NLS-enabled path name) 


Example 


The following example creates and opens an output file for exclusive access. This program was stored in a 
source file with CCSID 37, so the constant string "newfile" will be compiled in CCSID 37. Therefore, the 
language and country or region specified are United States English, and the CCSID specified is 37. 


#include <fcntl.h> 
#include <stdio.h> 
#include <Qp0lstdi.h> 


main () 


{ 
int fildes; 


const char US_const[3]= "US"; 
const char Language_const [4]="ENU",; 


struct pnstruct 
{ 
Qlg_Path_Name_T gqlg_struct; 
char pn[7]; 
}; 
struct pnstruct pns; 
struct pnstruct *pns_ptr = NULL; 


char fn[]="newfile"; 


memset ((void*)&pns, 0x00, sizeof(struct pnstruct)); 
pns.qlg_struct.CCSID = 37; 

memcpy (pns.qlg_struct.Country_ID,US_const, 2); 

memcpy (pns.qlg_struct.Language_ID, Language_const,3);; 
pns.qlg_struct.Path_Type = 0; 
pns.qlg_struct.Path_Length = sizeof(fn) - 1; 
pns.gqlg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (pns.pn, fn, sizeof (fn)-1); 


pns_ptr = &pns; 
if (fildes = QlgOpen((Qlg_Path_Name_T *)pns_ptr, 
O_WRONLY|O_CREAT|O_EXCL, S_IRWXU)) == -1) 


{ 


perror ("QlgOpen() error"); 


} 
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QlgOpen64()--Open File (large file enabled and 
using NLS-enabled path name) 


Syntax 


#include <fcntl.h> 


int QlgOpen64(Qlg_Path_Name_T *path, int oflag, 


Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgOpen64() function, like the open64() and open() functions, opens a file and returns a number 
called a file descriptor. QlgOpen64() differs from open64() in that the open64() function takes a pointer to 
a Qlg_ Path _Name_T structure, while open64() takes a pointer to a character string. QlgOpen64() differs 
from open() in that it automatically opens a file with the O_LARGEFILE flag set. 


Limited information on the path parameter is provided here. For more information on the path parameter 
and for a discussion of other parameters, authorities required, return values, and related information, see 
open()--Open a File or QlgOpen64()--Open File (Large File Enabled). 


Parameters 


path 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path 
name of the file to be opened. For more information on the Qlg_Path_Name_T structure, see Path 


name format. 


Related Information 
@ open()--Open a File 
e QlgCreat()--Create or Rewrite File (using NLS-enabled path name) 


e QlgStatQ--Get File Information (using NLS-enabled path name) 


API introduced: V5R1 
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QlgOpendir()--Open Directory (using NLS-enabled 
path name) 


Syntax 


#include <sys/types.h> 
#include <dirent.h> 


DIR *QlgOpendir (Qlg_Path_Name_T *dirname) ; 


Service Program Name: QPOLLIB1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgOpendir() function, like the opendir( function, opens a directory so it can be read. The difference is 
that the QlgOpendir( function takes a pointer to a Qlg_Path_Name_T structure, while the opendir() function 
takes a pointer to a character string. The QlgOpendir() function opens a directory so it can be read with the 
QlgReaddir() function. 


Names returned on calls to QlgReaddir() are returned in the coded character set identifier (CCSID) specified at 
the time the directory is opened. QlgOpendir() allows the CCSID to be specified in the Qlg_Path_Name_T 
structure. opendir() uses the CCSID that is in effect for the current job at the time the opendir() function is 
called. See opendir()--Open Directory for more on the job CCSID. 


Limited information on the dirname parameter is provided here. For more information on the dirname parameter 
and for a discussion of authorities required, return values, and related information, see opendir()--Open Directory. 


Parameters 


dirname 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path name 
of the directory to be opened. For more information on the Qlg_Path_Name_T structure, see Path name 


format. 
Related Information 


@ opendir(--Open Directory 


e@ QlgReaddir()--Read Directory Entry (using NLS-enabled path name) 
e@ QlgSpawn()--Spawn Process (using NLS-enabled path name) 


e@ QlgSpawnpQ--Spawn Process with Path (using NLS-enabled fileh name) 


Example 
The following example opens a directory: 


#include <sys/types.h> 
#include <dirent.h> 
#include <sys/stat.h> 
#include <sys/types.h> 
#include <errno.h> 
#include <stdio.h> 


void traverse(char *fn, int indent) { 
DIR; *diuwn; 
int count; 
struct stat info; 


typedef struct my_dirent_lg 
{ 
struct dirent_lg *entry; 
char d_lg_name[1]; 
}; 


struct my_dirent_lg lg_struct; 
struct dirent_lg *entry; 


const char US_const[3]= "US"; 
const char Language_const[4]="ENU"; 
typedef struct pnstruct 
{ 
Qlg_Path_Name_T gqlg_struct; 
char pn[1025]; /* This array size must be >= * / 
/* the length of the path name or */ 
/* this must be a pointer to the if 
/* path name. */ 


}; 


struct pnstruct path; 
struct pnstruct path_to_stat; 
char *temp_char_path[1025]; 


[ROK KK KK KK KK A A A AAA I  / 


/* Initialize Qlg_Path_Name_T structure, since the path name */ 
{* was not in the Qlg_Path_Name_T format when this function */ 
je was called. */ 


[ROK KK KK KKK A A A A AA OK  / 


memset ((void*) &path, 0x00, sizeof(struct pnstruct)); 
path.qlg_struct.CCSID = 37; 

memcpy (path.qlg_struct.Country_ID,US_const,2); 

memcpy (path.qlg_struct.Language_ID, Language_const, 3) ; 
path.qlg_struct.Path_Type = QLG_CHAR_SINGLE; 
path.qlg_struct.Path_Name_Delimiter[0] = '/'; 
path.qlg_struct.Path_Length = strlen(fn); 

memcpy (path.pn,fn,strilen(fn)); 


for (count=0; count < indent; count++) printf(" "); 
printf("%s\n", fn); 


if ((dir = QlgOpendir((Qlg_Path_Name_T *)é&path)) == NULL) 


perror("QlgOpendir() error"); 
else 


{ 
path_to_stat = path; 


while ((entry = QlgReaddir(dir)) != NULL) 
{ 
if 
(entry->d_lg_name[0] != '.") 


/* Concat the components of the path name into a */ 
/* Qlg_Path_Name_T structure that is used on the */ 


/* next function that is called. Clear and */ 
/* use a temporary buffer to ensure that only */ 
/* characters returned by QlgReaddir() are * / 
/* included in the concatenated path name */ 
/* structure. a) 


strcpy (path_to_stat.pn,path.pn); 
strcat (path_to_stat.pn, "/"); 
memset (temp_char_path, 0x00,1025); 
memcpy (temp_char_path, 
entry—->d_lg_name, entry->d_lg_qlg.Path_Length) ; 


strcat (path_to_stat.pn, (char *) &temp_char_path) ; 


/* Calculate the size of the path, including the */ 
/* length of the path specified on the open, the */ 
/* length of the name returned by QlgReaddir(), * / 
/* and the delimiter. a) 


path_to_stat.qlg_struct.Path_Length = 


(path.qlg_struct.Path_Length + 
entry->d_lg_qlg.Path_Length + 1); 


/* Call QlgStat() to determine if the path name * / 


/* is a directory. */ 
if (QlgStat ((Qlg_Path_Name_T *) &path_to_stat, 
&info) != 0) 
{ 
fprintf(stderr, "QlgStat() error on %s: %s\n", 


path_to_stat.pn, 
strerror(errno)); 
} 
else if (S_ISDIR(info.st_mode) ) 
{ 
/* this a directory so loop to open its objects.*/ 
traverse (path_to_stat.pn, indent+1); 
} 
else printf(" %s\n",path_to_stat.pn); 
} 
} 


closedir(dir); 


main() { 


puts ("Directory structure:"); 
traverse("/etc", 0); 


} 
Output: 


Directory structure: 
/etc 
/etc/samples 
/etc/samples/IBM 
/etc/IBM 
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QlgPathconf()--Get Configurable Path Name 
Variables (using NLS-enabled path name) 


Syntax 


#include <unistd.h> 


long QlgPathconf (Qlg_Path_Name_T *path, int name); 


Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgPathconf() function, like the pathconf() function, lets an application determine the value of a 
configuration variable (name) associated with a particular file or directory (path). The difference is that the 
QlgPathconf() function takes a pointer to a Qlg_Path_Name_T structure, while pathconf() takes a pointer 
to a character string. 


Limited information on the path parameter is provided here. For more information on the path parameter 
and for a discussion of other parameters, authorities required, return values, and related information, see 
pathconf()--Get Configurable Path Name Variables. 


Parameters 


path 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path 
name for which the value of the configuration variable is requested. For more information on the 
Qlg_ Path_Name_T structure, see Path name format. 


Related Information 


e fpathconf()--Get Configurable Path Name Variables by Descriptor 


e pathconf()--Get Configurable Path Name Variables 


e@ QlgChown()--Change Owner and Group of File (using NLS-enabled path name) 


Example 


The following example determines the maximum number of bytes in a file name: 


#include <stdio.h> 
#include <unistd.h> 
#include <errno.h> 


main() { 
long result; 
#define mypath "/" 
const char US_const[3]= "US"; 
const char Language_const[4] ="ENU"; 
typedef struct pnstruct 
{ 
Qlg_Path_Name_T qlg_struct; 
char pn[100]; /* This array size must be >= the */ 
/* length of the path name or must */ 
/* be a pointer to the path name. */ 


}; 
struct pnstruct path; 


[KR KK KKK RK KK KK I RK I EK RK KK KKK / 


/* Initialize Qlg_Path_Name_T parameters */ 
[BRK KK KK RK KK KK KI I ER RK KK KKK / 


memset ((void*) &path, 0x00, sizeof(struct pnstruct)); 
path.glg_struct.CCSID = 37; 

memcpy (path.gqlg_struct.Country_ID, US_const,2); 

memcpy (path.gqlg_struct.Language_ID, Language_const, 3); 
path.glg_struct.Path_Type = QLG_CHAR_SINGLE; 
path.gqlg_struct.Path_Length = sizeof (mypath) -1; 
path.qlg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (path.pn,mypath, sizeof (mypath) -1); 


errno = 0; 

puts ("examining NAME MAX limit for root filesystem"); 

if ((result = QlgPathconf((Qlg_Path_Name_T *) &épath, 
_PC_NAME_ MAX)) == -1) 


if (errno == 0) 
puts ("There is no limit to NAME_MAX."); 
else perror("QlgPathconf() error"); 
else 
printf ("NAME_MAX is %ld\n", result); 
} 


Output: 


examining NAME _MAX limit for root filesystem 
NAME_MAX is 255 
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QigProcessSubtree()--Process a Path Name 
(using NLS-enabled path name) 


Syntax 


#include <Qp0lstdi.h> 


int QlgProcessSubtree ( 

Qlg_Path_Name_T *Path_Name, 

uint Subtree_level, 
Qp0l_Objtypes_List_t *Objtypes_array_ptr, 

uint Local_remote_obj, 
QpOl_IN_EXclusion_List_t *IN_EXclusion_ptr, 

uint Err_recovery_action, 
Qp0l_User_Function_t *UserFunction_ptr, 

void *Function_CtiBlk_ptr, ...); 


Service Program Name: QPOLLIB2 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


For a description of this function and information on its parameters, authorities required, return values, 
error conditions, error messages, usage notes, and related information, see Qp0|ProcessSubtree()--Process a 
Path Name. 


API introduced: V5R1 
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QligReaddir()--Read Directory Entry (using 
NLS-enabled path name) 


Syntax 


#include <sys/types.h> 
#include <dirent.h> 


struct dirent_lg *QlgReaddir(DIR *dirp); 
Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


The QlgReaddir() function, like the readdir() function, returns a pointer to a structure describing the next 
directory entry in the directory stream associated with dirp. The difference is that the QlgReaddir() 
function takes a pointer to a dirent_lg structure, while readdir() takes a pointer to a dirent structure. 


Limited information on the dirp parameter is provided here. For more information on the dirp parameter 
and for a discussion of authorities required, return values, and related information, see readdir()--Read 
Directory Entry. 


Parameters 


dirp 


(Input) A pointer to DIR that refers to the open directory stream to be read. This pointer is returned 
by QlgOpendir(). 


A dirent_lg structure has the following contents: 


char d_reserved1[16] Reserved. 

unsigned int d_fileno_gen_id The generation ID associated with the file ID. 

ino_t d_fileno The file ID of the file. This number uniquely 
identifies the object within a file system. 

unsigned int d_reclen The length of the directory entry in bytes. 

int d_reserved3 Reserved. 

char d_reserved4[6] Reserved. 


char d_reserved5[2] Reserved. 


Qlg_ Path_Name_T d_lg_ name A Qlg_Path_Name_T that gives the name of a 
file in the directory. The path name is not 
null-terminated within the structure. The 
structure also provides National Language 
Support information, which includes ccsid, 
country_id, and language_id. This structure has 
a maximum length of 
{_QPOL_DIR_NAME_LG} bytes. For more 
information on the Qlg_Path_Name_T structure, 
see Path name format. 


Related Information 


e readdir()--Read Directory Entry 
e@ QlgOpendir(--Open Directory (using NLS-enabled path name) 


e QlgPathconf()--Get Configurable Path Name Variables (using NLS-enabled path name) 


Example 
The following example reads the contents of a root directory: 


#include <sys/types.h> 
#include <dirent.h> 
#include <errno.h> 
#include <stdio.h> 


main() { 


typedef struct my_dirent_lg 
{ 
struct dirent_lg *entry; 
char d_lg_name[1]; 
}; 


struct my_dirent_lg lg_struct; 
struct dirent_lg *entry; 
#define mypath "/" 
const char US_const[3]= "US"; 
const char Language_const [4]="ENU",; 
typedef struct pnstruct 
{ 
Qlg_Path_Name_T qlg_struct; 


char pn[100]; /* This array size must be >= */ 
/* the length of the path name */ 
/* or this must be a pointer ey 


/* to the path name. ef 
}; 


struct pnstruct path; 
DIR dix; 


[KR KK KK KR RK KK KK KK EE RK KK KK / 


/* Initialize Qlg_Path_Name_T parameters */ 
[OR KK KK RK KK KK KK I I EK RK KK KK / 


memset ((void*) &path, 0x00, sizeof(struct pnstruct)); 
path.gqlg_struct.CCSID = 37; 

memcpy (path.gqlg_struct.Country_ID, US_const,2); 

memcpy (path.gqlg_struct.Language_ID, Language_const, 3); 
path.glg_struct.Path_Type = QLG_CHAR_SINGLE; 
path.gqlg_struct.Path_Length = sizeof (mypath)-1; 
path.qlg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (path.pn,mypath, sizeof (mypath) -1); 


if ((dir = QlgOpendir((Qlg_Path_Name_T *)&path)) == NULL) 
perror ("QlgOpendir() error"); 
else { 
puts ("contents of root:"); 
while ((entry = QlgReaddir(dir)) != NULL) 
printf£(" s\n", entry->d_lg_name) ; 


closedir(dir); 


} 


Output: 


contents of root: 


OSYS.LIB 
QDLS 
QOpensys 
QOPT 
home 
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QlgReaddir_r()--Read Directory Entry (using 
NLS-enabled path name) 


Syntax 


#include <sys/types.h> 
#include <dirent.h> 


int QlgReaddir_r(DIR *dirp, struct dirent_lg *entry, 
struct dirent_lg **result); 


Service Program Name: QPOLLIBTS 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgReaddir_r() function, like the readdir_r() function, initializes a structure that is referenced by 
entry to represent the next directory entry in the directory stream that is associated with dirp. The difference 
is that the QlgReaddir_r() dirp parameter points to a dirent_lg structure, while the readdir_r() dirp 
parameter points to a dirent structure. 


The QlgReaddir_r functions stores a pointer to the entry structure at the location referenced by result. 


Limited information on the dirp parameter, the entry parameter, and the result parameter is provided here. 
For more information on these parameters and for a discussion of authorities required, return values, and 
related information, see readdir_r()--Read Directory Entry. 


Parameters 


dirp 
(Input) A pointer to a DIR that refers to the open directory stream to be read. This pointer is 
returned by QlgOpendir(). 


entry 
(Output) A pointer to a dirent_lg structure in which the directory entry is to be placed. 


result 


(Output) A pointer to a pointer to a dirent_lg structure. Upon successfully reading a directory entry, 
this dirent_lg pointer is set to the same value as entry. Upon reaching the end of the directory 
stream, this pointer is set to NULL. 


A dirent_lg structure has the following contents: 


char d_reserved1[16] Reserved. 
unsigned int d_fileno_gen_id The generation ID associated with the file ID. 
ino_t d_fileno The file ID of the file. This number uniquely 


identifies the object within a file system. 


unsigned int d_reclen 


int d_reserved3 
char d_reserved4[6] 
char d_reserved5[2] 


Qlg_ Path_Name_T d_lg_ name 


Related Information 


e readdir()--Read Directory Entry 


The length of the directory entry in bytes. 
Reserved. 
Reserved. 
Reserved. 


A Qlg_Path_Name_T structure that gives the 
name of a file in the directory. The path name is 
not null-terminated within the structure. The 
structure also provides National Language 
Support information, which includes ccsid, 
country_id, and language_id. This structure has 
a maximum length of 
{_QPOL_DIR_NAME_LG} bytes. For more 
information on the Qlg_Path_Name_T structure, 
see Path name format. 


e@ QlgOpendirO--Open Directory (using NLS-enabled path name) 


e QlgPathconf()--Get Configurable Path Name Variables (using NLS-enabled path name) 


Example 


The following example reads the contents of a root directory: 


#include <sys/types.h> 
#include <dirent.h> 
#include <errno.h> 
#include <stdio.h> 


main() { 
int return_code; 
DIR *dir; 
struct dirent_lg entry; 
struct dirent_lg *result; 


typedef struct my_dirent_lg 
{ 
struct dirent_lg *entry; 
char d_lg_name[1]; 
}; 
struct my_dirent_lg lg_struct; 


#define mypath "/" 
const char US_const[3]= "US"; 


const char Language_const [4]="ENU",; 


typedef struct pnstruct 


Qlg_Path_Name_T qlg_struct; 

char pn[100]; /* This array size must be >= * / 
/* the length of the path name or this */ 
/* must be a pointer to the path name. */ 


}; 
struct pnstruct path; 


[BR KK KK RK KK KK KK RK EK RK KK KKK / 


/* Initialize Qlg_Path_Name_T parameters */ 
[KR KK KKK KK KK KK KR KK I EE KK RK KK KKK / 


memset ((void*) &path, 0x00, sizeof(struct pnstruct)); 
path.glg_struct.CCSID = 37; 

memcpy (path.gqlg_struct.Country_ID, US_const,2)j; 

memcpy (path.gqlg_struct.Language_ID, Language_const, 3); 
path.gqlg_struct.Path_Type = QLG_CHAR_SINGLE; 
path.gqlg_struct.Path_Length = sizeof (mypath)-1; 
path.gqlg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (path.pn,mypath, sizeof (mypath) -1); 


if ((dir = QlgOpendir((Qlg_Path_Name_T *)&path)) == NULL) 
perror ("QlgOpendir() error"); 
else { 
puts ("contents of root:"); 
for (return_code = QlgReaddir_r(dir, é&entry, &result); 
result != NULL && return_code == 0; 
return_code = QlgReaddir_r(dir, &entry, &result) ) 
printf£(" s\n", entry.d_lg_name) ; 
if (return_code != 0) 


perror ("QlgReaddir_r() error"); 
closedir (dir); 


} 
Output: 


contents of root: 


OSYS.LIB 
QDLS 
QOpensys 
QOPT 
home 
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QlgReadlink()--Read Value of Symbolic Link 
(using NLS-enabled path name) 


Syntax 


#include <unistd.h> 


int QlgReadlink(Qlg_Path_Name_T *path, Qlg_Path_Name_T *buf, 
size_t bufsiz); 


Service Program Name: QPOLLIB1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgReadlink() function, like the readlink( function, places the contents of the symboliclink path in the 
buffer buf. The difference is that the QlgReadlink() function uses pointers to Qlg_Path_Name_T structures, 
while readlink() uses pointers to character strings. 


Limited information on the path parameter, the buf parameter, and the size parameter is provided here. For more 
information on these parameters and for a discussion authorities required, return values, and related information, 
see readlink()--Read Value of Symbolic Link. 


Parameters 


path 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path name 
of the symbolic link. For more information on the Qlg_Path_Name_T structure, see Path name format. 


buf 
(Output) A pointer to the area in which the contents of the link should be stored. For more information on 
the Qlg_Path_Name_T structure, see Path name format. 


bufsiz 
(Input) The size of buf in bytes. 


Related Information 


e readlink()--Read Value of Symbolic Link 
e@ QlgLstat()--Get File or Link Information (using NLS-enabled path name) 
e@ QlgStatQ--Get File Information (using NLS-enabled path name) 


e@ QlgSymlinkQ--Make Symbolic Link (using NLS-enabled path name) 


e@ Qp0lUnlinkQ--Remove Link to File 


Example 
The following example uses QlgReadlink(): 


#include <unistd.h> 
#include <sys/types.h> 
#include <sys/stat.h> 
#include <fcntl.h> 
#include <stdio.h> 
#include <QpOlstdi.h> 


main() { 
int file_descriptor; 


#define mypath_fn "readlink.file" 
#define mypath_sl "readlink.symlink" 


const char US_const[3]= "US"; 
const char Language_const [4]="ENU"; 
typedef struct pnstruct 
{ 
Qlg_Path_Name_T qlg_struct; 
char pn[100]; /* This array size must be >= the length */ 
/* of the path name or this must be a */ 
/* pointer to the path name. */ 


}; 


struct pnstruct path_fn; 
struct pnstruct path_sl; 
struct pnstruct path_buf; 


[ROR KK KK KK KK KK HK A A A A A RK / 


/* Initialize Qlg_Path_Name_T parameters * / 
[OR KK KK KK KK KK A KA A KK 
memset ((void*)path name_fn, 0x00, sizeof(struct pnstruct)); 
path_fn.qlg_struct.CCSID = 37; 
memcpy (path_fn.qlg_struct.Country_ID,US_const,2); 
memcpy (path_fn.qlg_struct.Language_ID, Language_const, 3); 
path_fn.qlg_struct.Path_Type = QLG_CHAR_SINGLE; 
path_fn.qlg_struct.Path_Length = sizeof (mypath_fn)-1; 
path_fn.qlg_struct.Path_Name_Delimiter[0] = '/'; 
memcpy (path_fn.pn,mypath_fn, sizeof (mypath_fn)-1); 


memset ((void*)path name_sl, 0x00, sizeof(struct pnstruct)); 
path_sl.qlg_struct.CCSID = 37; 

memcpy (path_sl.qlg_struct.Country_ID,US_const,2); 

memcpy (path_sl.qlg_struct.Language_ID, Language_const, 3); 
path_sl.qlg_struct.Path_Type = QLG_CHAR_SINGLE; 
path_sl.qlg_struct.Path_Length = sizeof (mypath_s1l)-1; 
path_sl.qlg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (path_sl.pn,mypath_s1,sizeof (mypath_sl)-1); 


if ((file_descriptor = QlgCreat ((Qlg_Path_Name_T *)path name_fn, 


< 0) 
perror("QlgCreat() error"); 


else { 
close(file_descriptor) ; 
if (QlgSymlink((Qlg_Path_Name_T *) path name_fn, 
(Qlg_Path_Name_T *)path name_sl) != 0) 
perror("QlgSymlink() error"); 
else { 
if (QlgReadlink ((Qlg_Path_Name_T *)path name_sl, 
(Qlg_Path_Name_T *)path name_buf, 
sizeof (path_buf)) < 0) 
perror("QlgReadlink() error"); 
else printf ("QlgReadlink() returned '%s' for '%Ss'\n", 
path name_buf.pn, 
path name_sl.pn); 


QlgUnlink((Qlg_Path_Name_T *)path name_sl); 


} 
QlgUnlink ((Qlg_Path_Name_T *) path name_fn)j; 


} 
} 


Output: 


QlgReadlink() returned 'readlink.file' for 'readlink.symlink' 
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S_IWUSR) ) 


QigRenameKeep()--Rename File or Directory, 
Keep "new" If It Exists (using NLS-enabled 
path name) 


Syntax 


#include <Qp0lstdi.h> 


int QlgRenameKeep(Qlg_Path_Name_T *old, Qlg_Path_Name_T *new); 
Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgRenameKeep() function, like the Qp0IRenameKeep() function, renames a file or a directory 
specified by old to the name given by new. The difference is that the QlgRenameKeep() function takes 
pointers to Qlg_Path_Name_T structures, while Qp0IRenameKeep() takes pointers to character strings. 


Limited information on the old and new parameters is provided here. For more information on these 
parameters and for a discussion of the authorities required, return values, and related information, see 
QpO0lRenameKeep()--Rename File or Directory, Keep "new" If It Exists. 


Parameters 


old 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to the 
path name of the file to be renamed. For more information on the Qlg_Path_Name_T structure, see 
Path name format. 


new 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to the 
path name of the new name for the file. For more information on the Qlg_Path_Name_T structure, 
see Path name format. 


Related Information 


e@ Qp0lRenameKeep()--Rename File or Directory, Keep "new" If It Exists 


e QlgPathconf()--Get Configurable Path Name Variables (using NLS-enabled path name) 


e@ QlgRenameUnlink()--Rename File or Directory, Unlink "new" If It Exists (using NLS-enabled path 
name) 


Example 


When you pass two file names to this example, it changes the first file name to the second file name using 
QlgRenameKeep(). 


#include <Qp0lstdi.h> 
#include <stdio.h> 


int main(int argc, char **argv) 


{ 


if ( arge != 3 ) 
{ 


printf( "Usage: $s old_fn new_fn\n", argv[0]); 


perror ( "Could not rename file" ); 
} 
else 
{ 

const char US_const[3]= "US"; 

const char Language_const [4]="ENU",; 


typedef struct pnstruct 
{ 
Qlg_Path_Name_T qlg_struct; 
/*** EXTRA STORAGE MAY BE NEEDED ***/ 
char pn[1025]; /* This size must be >= the path */ 
/* name length or a pointer to x 
/* the path name. */ 


}; 
struct pnstruct path_old; 
struct pnstruct path_new; 


struct pnstruct *path_old_ptr; 
struct pnstruct *path_new_ptr; 


memset ((void*) &path_old, 0x00, sizeof(struct pnstruct)); 
path_old_ptr = &path_old; 


path_old.glg_struct.CCSID = 37; 

memcpy (path_old.gqlg_struct.Country_ID, US_const,2); 

memcpy (path_old.gqlg_struct.Language_ID, Language_const, 3) ;; 
path_old.glg_struct.Path_Type = 0; 
path_old.glg_struct.Path_Length = strlen(argv[1]); 
path_old.qlg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (path_old.pn,argv[1],sizeof(argv[1])-1); 


memset ((void*) &path_new, 0x00, sizeof(struct pnstruct)); 
path_new_ptr = &path_new; 


path_new.glg_struct.CCSID = 37; 
memcpy (path_new.gqlg_struct.Country_ID, US_const,2)j; 


memcpy (path_new.gqlg_struct.Language_ID, Language_const, 3) ;; 
path_new.gqlg_struct.Path_Type = 0; 
path_new.gqlg_struct.Path_Length = strlen(argv[2]); 
path_new.qlg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (path_new.pn,argv[2],sizeof(argv[2])-1); 


if (QlgRenameKeep ((Qlg_Path_Name_T *)path_old_ptr, 
(Qlg_Path_Name_T *)path_new_ptr ) != 0) 


{perror ( "Could not rename file." ); } 
else {perror ( "File renamed." ); } 


} 
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QigRenameUnlink()--Rename File or Directory, 
Unlink "new" If It Exists (using NLS-enabled 
path name) 


Syntax 


#include <Qp0lstdi.h> 


int QlgRenameUnlink (Qlg_Path_Name_T *old, Qlg_Path_Name_T *new); 
Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgRenameUnlink() function, like the Qp0IRenameUnlink() function, renames a file or a directory 
specified by old to the name given by new. The difference is that the QlgRenameUnlink() function takes a 
pointer to a Qlg_ Path_Name_T structure, while Qp0IRenameUnlink() takes a pointer to a character string. 


Limited information on the old and old parameters is provided here. For more information on these 
parameters and for a discussion of the authorities required, return values, and related information, see 
Qp0lRenameUnlink()--Rename File or Directory, Unlink "new" If It Exists. 


Parameters 


old 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path 
name of the file to be renamed. For more information on the Qlg_Path_Name_T structure, see Path 


name format. 


new 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path 
name of the new name of the file. For more information on the Qlg_ Path_Name_T structure, Path 


name format. 


Related Information 


e Qp0lRenameUnlink(--Rename File or Directory, Unlink "new" If It Exists 


e QlgPathconf()--Get Configurable Path Name Variables (using NLS-enabled path name) 


e QlgRenameKeep()--Rename File or Directory, Keep "new" If It Exists (using NLS-enabled path 


name) 


Example 


When you pass two file names to this example, it tries to change the file name from the first name to the 
second using QlgRenameUnlink(). 


#include <Qp0lstdi.h> 
#include <stdio.h> 


int main(int argc, char **argv) 


{ 


if ( arge != 3 ) 
{ 


printf( "Usage: %s old_fn new_fn\n", argv[0]); 


perror ( "Could not unlink the file" ); 
} 
else 
{ 

const char US_const[3]= "US"; 

const char Language_const [4]="ENU",; 


typedef struct pnstruct 


{ 
Qlg_Path_Name_T qlg_struct; 
/*** EXTRA STORAGE MAY BE NEEDED ***/ 


char pn[1025]; /* This size must be >= the path */ 
/* name length or a pointer to mf 
/* the path name. e 


}; 
struct pnstruct path_old; 
struct pnstruct path_new; 


struct pnstruct *path_old_ptr; 
struct pnstruct *path_new_ptr; 


memset ((void*) &path_old, 0x00, sizeof(struct pnstruct)); 
path_old_ptr = &path_old; 


path_old.glg_struct.CCSID = 37; 

memcpy (path_old.gqlg_struct.Country_ID, US_const,2)j; 

memcpy (path_old.gqlg_struct.Language_ID, Language_const, 3) ;; 
path_old.glg_struct.Path_Type = 0; 
path_old.glg_struct.Path_Length = strlen(argv[1]); 
path_old.qlg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (path_old.pn,argv[1],sizeof(argv[1])); 


memset ((void*) &path_new, 0x00, sizeof(struct pnstruct)); 
path_new_ptr = &path_new; 


path_new.glg_struct.CCSID = 37; 


memcpy (path_new.gqlg_struct.Country_ID, US_const,2); 

memcpy (path_new.gqlg_struct.Language_ID, Language_const, 3) ;; 
path_new.gqlg_struct.Path_Type = 0; 
path_new.glg_struct.Path_Length = strlen(argv[2]); 
path_new.gqlg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (path_new.pn,argv[2],sizeof(argv[2])); 


if (QlgRenameUnlink((Qlg_Path_Name_T *)path_old_ptr, 


(Qlg_Path_Name_T *)path_new_ptr ) != 0) 
{perror ( "Could not unlink the file." ); } 
else {perror ( "File unlinked." ); } 


} 
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QlgRmdir()--Remove Directory (using 
NLS-enabled path name) 


Syntax 


#include <unistd.h> 


int QlgRmdir(Qlg_Path_Name_T *path,); 


Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgRmdir( function, like the rmdir() function, removes a directory, path, provided that the directory is 
empty; that is, the directory contains no entries other than "dot" (.) or "dot-dot" (..). The difference is that the 
QlgRmdir() function takes a pointer to a Qlg_Path_Name_T structure, while rmdir() takes a pointer to a 
character string. 


Limited information on the path parameter is provided here. For more information on the path parameter and 
for a discussion of authorities required, return values, usage notes, and related information, see 
rmdirQ--Remove Directory. 


Parameters 


path 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path name 
of the directory to be removed. For more information on the Qlg_Path_Name_T structure, see Path 


name format. 


Related Information 


e@ rmdir()--Remove Directory 
e@ QlgMkdirQ--Make Directory (using NLS-enabled path name) 


e@ Qp0lUnlinkQ--Remove Link to File (using NLS-enabled path name) 


Example 
The following example removes a directory: 


#include <sys/stat.h> 


#include <unistd.h> 
#include <stdio.h> 
#include <sys/stat.h> 
#include <fcntl.h> 
#include <Qp0lstdi.h> 


main() { 


#define mypath_d "new_dir" 
#define mypath_f "new_dir/new_file" 


const char US_const[3]= "US"; 
const char Language_const[4] ="ENU",; 
typedef struct pnstruct 
{ 
Qlg_Path_Name_T qlg_struct; 
char pn[100]; /* This array size must be >= the */ 
/* length of the path name or must */ 
/* be a pointer to the path name. */ 


}; 
struct pnstruct path_d; 
struct pnstruct path_f; 


int file_descriptor; 


[BRK KKK KK KK KK KK KR RK KK KK KK KR KK KK KK KK Ke / 


/* Initialize Qlg_Path_Name_T parameters Ai /; 
[BRK KKK KK KK KK KK KR KK KK KK KR KK KK KK KK KK KK Ke / 
memset ((void*) &path_d, 0x00, sizeof(struct pnstruct) ); 
path_d.qlg_struct.CCSID = 37; 
memcpy (path_d.qlg_struct.Country_ID,US_const,2); 
memcpy (path_d.gqlg_struct.Language_ID, Language_const, 3); 
path_d.qlg_struct.Path_Type = QLG _CHAR_SINGLE; 
path_d.qlg_struct.Path_Length = sizeof (mypath_d)-1; 
path_d.qlg_struct.Path_Name_Delimiter[0] = '/'; 
memcpy (path_d.pn,mypath_d, sizeof (mypath_d)-1); 


memset ((void*) &path_f, 0x00, sizeof(struct pnstruct) ); 
path_f.qlg_struct.CCSID = 37; 

memcpy (path_f.qlg_struct.Country_ID,US_const, 2); 

memcpy (path_f.qlg_struct.Language_ID, Language_const, 3); 
path_f.qlg_struct.Path_Type = QLG_CHAR_SINGLE; 
path_f.qlg_struct.Path_Length = sizeof (mypath_f)-1; 
path_d.qlg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (path_f.pn,mypath_f, sizeof (mypath_f)-1); 


if (QlgMkdir((Qlg_Path_Name_T *) &path_d,S_IRWXU|S_IRGRP|S_IXGRP) ! 
perror("QlgMkdir() error"); 
else if ((file_descriptor = QlgCreat ((Qlg_Path_Name_T *) &path_f,S_IWUSR) ) 


perror("QlgCreat() error"); 
else { 

close(file_descriptor) ; 

QlgUnlink ((Qlg_Path_Name_T *) &path_f); 
} 


if (QlgRmdir((Qlg_Path_Name_T *)&path_d) != 0) 
perror("QlgRmdir() error"); 


else 
puts ("removed!"); 
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QligSaveStgFree()--Save Storage Free (using 
NLS-enabled path name) 


Syntax 


#include <Qp0lstdi.h> 


int QlgSaveStgFree ( 
Qlg_Path_Name_T *Path_Name, 
Qp0l_StgFree_Function_t *UserFunction_ptr, 
void *Function_CtlBlk_ptr); 


Service Program Name: QPOLLIB3 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


For a description of this function and more information on the parameters, authorities required, return 
values, error conditions, error messages, usage notes, and related information, see Qp0ISaveStgFree()--Save 


Storage Free. 
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QlgSetAttr()--Set Attributes (using NLS-enabled 
path name) 


Syntax 


#include <Qp0lstdi.h> 
int QlgSetAttr 
(Qlg_Path_Name_T *Path_Name, 
char *Buffer_ptr, 
uint Buffer_Size, 
uint Follow_Symlnk, ...); 


Service Program Name: QPOLLIB3 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


For a description of this function and information on its parameters, authorities required, return values, 
error conditions, error messages, usage notes, and related information, see Qp0|]SetAttrQ--Set Attributes. 
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QlgStat()--Get File Information (using 
NLS-enabled path name) 


Syntax 


#include <sys/stat.h> 


int QlgStat(Qlg_Path_Name_T *path, struct stat *buf); 


Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgStat() function, like the stat() function, gets status information about a specified file and places it 
in the area of memory pointed to by the buf argument. The difference is that the QlgStat() function takes a 
pointer to a Qlg_Path_Name_T structure, while stat() takes a pointer to a character string. 


Limited information on the path parameter is provided here. For more information on the path parameter 
and for a discussion of other parameters, authorities required, return values, and related information, see 
stat()--Get File Information. 


Parameters 


path 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path 
name of the file from which information is required. For more information on the 
Qlg_ Path_Name_T structure, see Path name format. 


Related Information 


e stat()--Get File Information 

e QlgStat64()--Get File Information (large file enabled and using NLS-enabled path name) 
e QlgChmod()--Change File Authorizations (using NLS-enabled path name) 

e@ QlgChown()--Change Owner and Group of File (using NLS-enabled path name) 

e QlgCreat()--Create or Rewrite File (using NLS-enabled path name) 

e QlgLink(--Create Link to File (using NLS-enabled path name) 

e QleLstat()--Get File or Link Information (using NLS-enabled path name) 

e OlgMkdirQ--Make Directory (using NLS-enabled path name) 

e QlgReadlink()--Read Value of Symbolic Link (using NLS-enabled path name) 


e QleSymlinkQ--Make Symbolic Link (using NLS-enabled path name) 
e OQlgUtime(Q--Set File Access and Modification Times (using NLS-enabled path name) 


e 01Unlink()--Remove Link to File 


Example 


The following example gets status information about a file: 


#include <sys/types.h> 
#include <sys/stat.h> 
#include <stdio.h> 
#include <time.h> 


main() { 
struct stat info; 
#define mypath "/" 


const char US_const[3]= "US"; 
const char Language_const [4] 
typedef struct pnstruct 


{ 


Qlg_Path_Name_T qlg_struct; 
char pn[100]; /* This array size must be >= the 


/* length of the path name or must */ 
/* be a pointer to the path name. 


}; 
struct pnstruct path; 


="ENU"; 


[KR RK KK KK KK KK IK KE EK EK KK KK KKK / 


/* Initialize Qlg_Path_Name_T parameters 


Me 


[KK KK KKK KK KK KK KI KK EE KK KK KK KKK / 


memset ((void*) &path, 


0x00, sizeof(struct pnstruct)); 


path.glg_struct.CCSID = 37; 
memcpy (path.gqlg_struct.Country_ID, US_const,2)j; 


memcpy (path.gqlg_struct.Language_ID, Language_const, 3); 
path.glg_struct.Path_ 
path.glg_struct.Path_ 


Type = QLG _CHAR_SINGLE; 
sizeof (mypath) -1; 


Length = 


path.gqlg_struct.Path_Name_Delimiter[0] = 
memcpy (path.pn,mypath, sizeof (mypath) -1); 


if (QlgStat ((Qlg_Path_Name_T *) &épath, 


(int) 
(int) 


info. 
info. 
info. 
info. 
info. 
info. 


perror ("QlgStat() error"); 
else { 

puts ("QlgStat() returned the following 
printf(" inode: Sd\n", 

printf (" dev id: Sd\n", 

printf (" mode: 308x\n", 

printf(" links: sda\n", 

printf (" uid: Sda\n", 

printf (" gid: sda\n", 


} 


up ae 


&info) != 0) 


information about root f/s: 


st_ino); 
st_dev); 
st_mode); 


st_nlink); 


st_uid); 
st_gid); 


Output: note that the following information will vary from system to system. 


) 


QlgStat() returned the following information about root f/s: 
inode: 0 


dev id: 1 
mode: 01000led 
links: 5 
uid: 137 
gid: 500 
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QlgStat64()--Get File Information (large file 
enabled and using NLS-enabled path name) 


Syntax 


#include <sys/stat.h> 


int QlgStat64(Qlg_Path_Name_T *path, struct stat64 *buf); 
Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


TheQlgStat64() function, like the stat64() function, gets status information about a specified file and places it 
in the area of memory pointed to by the buf argument. The difference is that the QlgStat64() function takes a 
pointer to a Qlg_Path_Name_T structure, while stat64() takes a pointer to a character string. 


Limited information on the path parameter is provided here. For more information on the path parameter and 
for a discussion of other parameters, authorities required, return values, and related information, see 
stat64()--Get File Information (Large File Enabled). 


Parameters 


path 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path name 
of the file from which information is required. For more information on the Qlg_ Path_Name_T 
structure, see Path name format. 


Related Information 


e stat()--Get File Information 


@ stat64(--Get File Information (Large File Enabled) 


Example 
The following example gets status information about a file: 


#define _LARGE FILE API 


#include <sys/types.h> 
#include <sys/stat.h> 
#include <stdio.h> 


#include <time.h> 


main() { 
struct stat64 info; 
#define mypath "/" 
const char US_const[3]= "US"; 
const char Language_const[4] ="ENU",; 
typedef struct pnstruct 
{ 
Qlg_Path_Name_T qlg_struct; 
char pn[100]; /* This array size must be >= the */ 
/* length of the path name or this must */ 
/* be a pointer to the path name. */ 


}; 
struct pnstruct path; 


[RK KK KK KR KKK KK KK KR KK KK KK KK KK KK KK Ke / 


/* Initialize Qlg_Path_Name_T parameters ues 
[KKK KKK KKK KKK KK KK KK KK KK KK KK KK KKK KK KK KKK KK KK KK KK KK KK KKK KK KK KK KK KK / 
memset ((void*)&path, 0x00, sizeof (struct pnstruct)); 
path.glg_struct.CCSID = 37; 
memcpy (path.qlg_struct.Country_ID,US_const, 2); 
memcpy (path.gqlg_struct.Language_ID, Language_const, 3); 
path.qlg_struct.Path_Type = QLG_CHAR_SINGLE; 
path.qlg_struct.Path_Length = sizeof (mypath)-1; 
path.glg_struct.Path_Name_Delimiter[0] = '/'; 
memcpy (path.pn,mypath, sizeof (mypath) ); 


if (QlgStat64((Qlg_Path_Name_T *)&path, &info) != 0) 
perror("QlgStat64() error"); 
else { 
puts ("QlgStat64() returned the following information about root f/s 
printf(" inode: Sda\n", (int) info.st_ino); 
printf(" dev id: Sda\n", (int) info.st_dev); 
printf (" mode: 308x\n", info.st_mode); 
printf(" links: Sd\n", info.st_nlink); 
printf (" uid: Sda\n", (int) info.st_uid); 
printf (" gid: sda\n", (int) info.st_gid); 


Output: note that the following information will vary from system to system. 


QlgStat64() returned the following information about root f/s: 
inode: 0) 


dev id: 1 
mode: 010001led 
links: 3 
uid: 137 
gid: 500 
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oh 


QlgStatvfs()--Get File System Information 
(using NLS-enabled path name) 


Syntax 


#include <sys/statvfs.h> 


int QlgStatvfs(Qlg_Path_Name_T *path, struct statvfs *buf); 


Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgStatvfs() function, like the statvfs() function, gets status information about the file system that 
contains the file named by the path argument. The difference is that the QlgStatvfs() function takes a 
pointer to a Qlg_ Path_Name_T structure, while statvfs() takes a pointer to a character string. 


Limited information on the path parameter is provided here. For moreinformation on the path parameter 
and for a discussion of other parameters, authorities required, return values, and related information, see 
statvfs(Q--Get File System Information. 


Parameters 


path 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path 
name of the file from which file system information is required. For more information on the 
Qlg_ Path_Name_T structure, see Path name format. 


Related Information 


e statvfsQ--Get File System Information 

e OlgStatvfs64()--Get File System Information (64-Bit Enabled and using NLS-enabled path name) 
e QlegChmod()--Change File Authorizations (using NLS-enabled path name) 

e QlgChown()--Change Owner and Group of File (using NLS-enabled path name) 

e QlgCreat()--Create or Rewrite File (using NLS-enabled path name) 

e QlgLink(--Create Link to File (using NLS-enabled path name) 

e QlgUtimeQ--Set File Access and Modification Times (using NLS-enabled path name) 

e O1UnlinkQ--Remove Link to File 


Example 


The following example gets status information about a file system: 


#include 
#include 
#include 


main() { 


struct 


<sys/statvfs.h> 
<stdio.h> 
<sys/types.h> 


statvfs info; 


#define mypath "/" 
const char US_const[3]= "US"; 
const char Language_const [4] 
typedef struct pnstruct 
{ 


="ENU"; 


Qlg_Path_Name_T qlg_struct; 
char pn[100]; /* This array size must be >= the */ 
/* length of the path name or must */ 
/* be a pointer to the path name. */ 
}; 
struct pnstruct path; 


[KKK KKK KK KK KK I KE I I I I IK KK / 


fx Initialize Qlg_Path_Name_T parameters */ 

[KKK KKK KK KK KE KI IE I I I KK KK KKK / 
memset ((void*)path name, 0x00, 
path.glg_struct.CCSID = 37; 
memcpy (path.gqlg_struct.Country_ID, US_const,2)j; 
memcpy (path.gqlg_struct.Language_ID, Language_const, 3); 
path.glg_struct.Path_Type = QLG_CHAR_SINGLE; 
path.gqlg_struct.Path_Length = sizeof (mypath)-1; 


sizeof (struct pnstruct)); 


path.gqlg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (path.pn,mypath, sizeof (mypath) -1); 

if (-1 == QlgStatvfs((Qlg_Path_Name_T *)path name, é&info) ) 
perror ("OQlgStatvfs() error"); 

else { 


puts ("QlgStatvfs() returned the following information"); 


puts("about the Root ('/') file system:"); 
printf(" f_bsize : Su\n", info.f_bsize); 
printf("  f_blocks S08XS08X\n", 

*( (int *)é&éinfo.f_blocks[0]), 

*( (int *)é&info.f_blocks[4])); 
printf(" f_bfree S08XS08X\n", 

*((int *)é&info.f_bfree[0]), 

*( (int *)éinfo.f_bfree[4])); 
printf("™ £files Su\n", info.f files); 
printf(" f_ffree Su\n", info.f_ffree); 
printt(” “f£-fsid Su\n", info.f_fsid); 
printf(" f_flag SX\n", info.f_flag); 
printf("  f_namemax Su\n", info.f_namemax) ; 
printf("  f_pathmax Su\n", info.f_pathmax) ; 
printf(" f_basetype s\n", info.f_basetype) ; 


Output: The following information will vary from file system to file system. 


QlgStatvfs() returned the following information 
about the Root ('/') file system: 
f_bsize : 4096 
f_blocks : OOODDD00002BF800 
f_bfree : 0000000000091703 
f_files : 4294967295 
f_ffree : 4294967295 
f_fsid : 0 
f_flag : 1A 
fonamemax : 255 
f pathmax : 4294967295 
f_basetype : "root" (/) 
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QigStatvfs64()--Get File System Information 
(64-Bit enabled and using NLS-enabled path 
name) 


Syntax 


#include <sys/statvfs.h> 


int QlgStatvfs64(Qlg_Path_Name_T *path, 
struct statvfs64 *buf 


Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgStatvfs64( function, like the statvfs64() function, gets status information about the file system that 
contains the file named by the path argument. The difference is that the QlgStatvfs64() function takes a 
pointer to a Qlg_Path_Name_T structure, while statvfs64() takes a pointer to a character string. 


Limited information on the path parameter is provided here. For more information on the path parameter 
and for a discussion of other parameters, authorities required, return values, and related information, see 
statvfs(Q--Get File System Information. 


Parameters 


path 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path 
name of the file from which file system information is required. For more information on the 
Qlg_ Path_Name_T structure, see Path name format. 


Related Information 


e statvfsQ--Get File System Information 


e statvfs64(--Get File System Information (64-Bit Enabled) 


Example 
The following example gets information about a file system. 


#include <sys/statvfs.h> 
#include <stdio.h> 
#include <sys/types.h> 


main() { 


struct statvfs info; 
#define mypath "/" 


const char US_const[3]= "US"; 
const char Language_const [4]="ENU",; 
typedef struct pnstruct 
{ 
Qlg_Path_Name_T qlg_struct; 
char pn[100]; 
/* This array size must be >= the length */ 
/* of the path name or must be a pointer */ 
/* to the path name. 7] 


}; 
struct pnstruct path; 


[OR KK KK KK KK KK KI KI I I EK KK KK KKK / 


p* Initialize Qlg_Path_Name_T parameters ef 
[RR KK KK KK KK KK KI I I I I I KK KKK / 


memset ((void*) &path, 0x00, sizeof(struct pnstruct)); 
path.glg_struct.CCSID = 37; 

memcpy (path.gqlg_struct.Country_ID, US_const,2)j; 

memcpy (path.gqlg_struct.Language_ID, Language_const, 3); 
path.glg_struct.Path_Type = QLG_CHAR_SINGLE; 
path.gqlg_struct.Path_Length = sizeof (mypath)-1; 
path.glg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (path.pn,mypath, sizeof (mypath) —) ; 


if (-1 == (QlgStatvfs64((Qlg_Path_Name_T *) &path, 
(struct statvfs64 *)&info))) 
{ 
perror ("OQlgStatvfs64() error"); 
} 
else 
{ 
puts ("QlgStatvfs64() returned the following information"); 
puts("about the Root ('/') file system:"); 


printf(" f_bsize : Su\n", info.f_bsize); 
printf(" f_blocks : S08X%S08X\n", 


*( (int *)é&éinfo.f_blocks[0]), 

*( (int *)&info.f_blocks[4])); 
printf(" f_bfree : S08X%08X\n", 

*((int *)&info.f_bfree[0]), 

*( (int *)&info.f_bfree[4])); 


printf(" f_files : Su\n", info.f_files); 
printt("- f£-ffree : Su\n", info.f_ffree); 


printf(" f_fsid : Su\n", info.f_fsid); 


printf(" f_flag : $X\n", 
printf(" f_namemax : %u\n", 
printf(" f_pathmax : %u\n", 
printf(" f_basetype : %s\n", 


} 
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info 
info 
info 
info 


.f_flag); 

. £_namemax 
.f_pathmax 
.f_basetyp 


) 
) 
e 


TY 


) 


TY 


QigSymlink()--Make Symbolic Link (using 
NLS-enabled path name) 


Syntax 


#include <unistd.h> 


int QlgSymlink ( 
Qlg_Path_Name_T *pname, Qlg_Path_Name_T *slink); 


Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgSymlink() function, like the symlink() function, creates the symbolic link named by slink with the 
value specified by pname. The difference is that the QlgSymlink() function takes a pointer to a 
Qlg_ Path_Name_T structure, while symlink() takes a pointer to a character string. 


Limited information on the *pname and the *slink parameter is provided here. For more information on 
these parameters and for a discussion of authorities required, return values, and related information, see 
symlink()--Make Symbolic Link. 


Parameters 


pname 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a value or a pointer to a value of 
the symbolic link. For more information on the Qlg_ Path_Name_T structure, see Path name format. 


slink 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a name or a pointer to a name of 
the symbolic link to be created. For more information on the Qlg_Path_Name_T structure, see Path 


name format. 


Related Information 


e symlinkQ--Make Symbolic Link 

e OQlgLink()--Create Link to File (using NLS-enabled path name) 

e@ QlgReadlinkQ--Read Value of Symbolic Link (using NLS-enabled path name) 
e@ Qp0lUnlinkQ--Remove Link to File 


Example 


The following example uses QlgSymlink(Q: 


#include 
#include 
#include 
#include 
#include 
#include 
#include 


main() { 


<stdio.h> 
<unistd.h> 
<sys/types.h> 
<sys/stat.h> 
<fentl.h> 
<stdlib.h> 
<Qp0lstdi.h> 


char buf[30]; 

int fd; 

#define mypath_fn "readlink.file" 
#define mypath_sl "readlink.symlink" 


const char US_const[3]= "US"; 
const char Language_const [4]="ENU",; 
typedef struct pnstruct 
{ 
Qlg_Path_Name_T qlg_struct; 
char pn[100]; /* This array size must be >= Af 
/* the length of the path name or */ 
/* this must be a pointer to the aia 
/* path name. */ 


}; 


struct pnstruct path_fn; 
struct pnstruct path_sl; 
struct pnstruct path_buf; 


[OR KK KKK KK KK KK KI KI EK KKK / 


[* Initialize Qlg_Path_Name_T parameters ef 
[KKK KK KK KK KK KI I I I I I I KK KK / 


memset ((void*) &path_fn, 0x00, sizeof(struct pnstruct)); 
path_fn.gqlg_struct.CCSID = 37; 

memcpy (path_fn.qlg_struct.Country_ID,US_const, 2); 

memcpy (path_fn.qlg_struct.Language_ID, Language_const, 3); 
path_fn.gqlg_struct.Path_Type = QLG _CHAR_SINGLE; 
path_fn.gqlg_struct.Path_Length = sizeof (mypath_fn)-1; 
path_fn.gqlg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (path_fn.pn,mypath_sl, sizeof (mypath_fn)-1); 


memset ((void*) &path_sl, 0x00, sizeof (struct pnstruct)); 
path_sl.qlg_struct.CCSID = 37; 

memcpy (path_sl.qlg_struct.Country_ID,US_const, 2); 

memcpy (path_sl.qlg_struct.Language_ID, Language_const, 3); 
path_sl.qlg_struct.Path_Type = QLG _CHAR_SINGLE; 
path_sl.gqlg_struct.Path_Length = sizeof (mypath_sl)-1; 
path_sl.gqlg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (path_sl.pn,mypath_sl, sizeof (mypath_sl)-1); 


if ((fd = QlgCreat ((Qlg_Path_Name_T *) &path_fn, S_IWUSR) ) 
< 0) 


perror ("QlgCreat() error"); 
else { 
close(fd); 
if (QlgSymlink ((Qlg_Path_Name_T *) &path_fn, 
(Qlg_Path_Name_T *)&path_sl) != 0) 
perror ("QlgSymlink() error"); 


else { 
if (QlgReadlink((Qlg_Path_Name_T *)&path_sl, 
(Qlg_Path_Name_T *) &path_buf, 
sizeof (struct pnstruct) ) 


< 0) 
perror ("QlgReadlink() error"); 


else printf("QlgReadlink() returned '%s' for 'Ss'\n", 
(Qlg_Path_Name_T *) &path_buf.pn, 
(Qlg_Path_Name_T *) &path_sl.pn); 


QlgUnlink((Qlg_Path_Name_T *) &path_sl)j; 
} 
QlgUnlink((Qlg_Path_Name_T *) &path_fn); 
} 


} 


Output: 


QlgReadlink() returned 'readlink.file' for 'readlink.symlink' 
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QligUnlink()--Remove Link to File (using 
NLS-enabled path name) 


Syntax 


#include <Qp0lstdi.h> 


int QlgUnlink(Qlg_Path_Name_T *Path_Name) ; 
Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes for open() API. 


The QlgUnlinkQ function, similar to the unlink() function, removes a directory entry that refers to a file. 
QlgUnlink(differs from unlink() in that the Path_Name parameter is a pointer to a Qlg_Path_Name_T 
structure instead of a pointer to a character string. 


For more information on the *Path_Name parameter and a discussion of the authorities required, return 
values, and related information, see unlink()--Remove Link to File. 


Parameters 


Path_Name 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path 
name of the object to be unlinked. For more information on the Qlg_ Path_Name_T structure, see 
Path name format. 


Related Information 


e unlinkQ--Remove Link to File 

e linkQ--Create Link to File 

e@ QlgOpen()--Open a File (using NLS-enabled path name) 

e QlgRmdir(--Remove Directory (using NLS-enabled path name) 


Example 


The following example removes a link to a file. This program was stored in a source file with CCSID 37, so 


the constant string "newfile" will be compiled in CCSID 37. Therefore, the country or region and language 
specified are United States English, and the CCSID specified is 37. 


#include <fcntl.h> 
#include <stdio.h> 
#include <Qp0Olstdi.h> 


main() { 
const char US_const[3]= "US"; 
const char Language_const [4]="ENU",; 


struct pnstruct 
{ 
Qlg_Path_Name_T gqglg_struct; 
char pn[7]; 
}; 
struct pnstruct pns; 
struct pnstruct *pns_ptr = NULL; 


char fn[]="unlink.file"; 


memset ((void*)&pns, 0x00, sizeof(struct pnstruct)); 
pns.qlg_struct.CCSID = 37; 

memcpy (pns.qlg_struct.Country_ID,US_const, 2); 

memcpy (pns.qlg_struct.Language_ID, Language_const,3);; 
pns.qlg_struct.Path_Type = 0; 
pns.qlg_struct.Path_Length = sizeof(fn)-1; 
pns.gqlg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (pns.pn, fn, sizeof (fn)-1); 


pns_ptr = &pns; 


if (QlgUnlink((Qlg_Path_Name_T *)&pns) != 0) 
{ 


perror ("QlgUnlink() error"); 
} 
else printf ("QlgUnlink() successful"); 
} 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


QligUtime()--Set File Access and Modification 
Times (using NLS-enabled path name) 


Syntax 


#include <utime.h> 


int QlgUtime(Qlg_Path_Name_T *path, const struct utimbuf 
*times) ; 


Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QlgUtime() function, like the utime() function, sets the access and modification times of path to the 
values in the utimbuf structure. The difference is that the QlgUtime() function takes a pointer to a 
Qlg_ Path_Name_T structure, while utime() takes a pointer to a character string. 


Limited information on the path parameter is provided here. For more information on the path parameter 
and for a discussion of other parameters, authorities required, return values, and related information, see 
utime()--Set File Access and Modification Times. 


Parameters 


path 


(Input) A pointer to a Qlg_Path_Name_T structure that contains a path name or a pointer to a path 
name of the file for which the times should be changed. For more information on the 
Qlg_ Path_Name_T structure, see Path name format. 


Related Information 


@ utime()--Set File Access and Modification Times 


Example 
The following example uses QlgUtime(): 


#include <utime.h> 
#include <time.h> 
#include <stdio.h> 
#include <sys/types.h> 
#include <sys/stat.h> 


#include <fcntl.h> 
#include <Qp0lstdi.h> 


main() { 
int file_descriptor; 
struct utimbuf ubuf; 
struct stat info; 


#define mypath "utime.file" 


const char US_const[3]= "US"; 
const char Language_const[4] ="ENU"; 
typedef struct pnstruct 
{ 
Qlg_Path_Name_T qlg_struct; 
char pn[100]; /* This array size must be >= the */ 
/* length of the path name or must */ 
/* be a pointer to the path name. */ 


}; 
struct pnstruct path; 


[KKK KK KK KK KK I KI IE I KK KKK / 


/* Initialize Qlg_Path_Name_T parameters eT 
[OR KK KKK KK KK KK KK KK / 


memset ((void*) &path, 0x00, sizeof(struct pnstruct)); 
path.glg_struct.CCSID = 37; 

memcpy (path.gqlg_struct.Country_ID, US_const,2)j; 

memcpy (path.gqlg_struct.Language_ID, Language_const, 3); 
path.glg_struct.Path_Type = QLG_CHAR_SINGLE; 
path.gqlg_struct.Path_Length = sizeof (mypath)-1; 
path.glg_struct.Path_Name_Delimiter[0] = '/'; 

memcpy (path.pn,mypath, sizeof (mypath) -1); 


if ((file_descriptor = 
QlgCreat ((Qlg_Path_Name_T *)&path, S_IWUSR)) < 0) 
perror("creat() error"); 
else { 


close(file_descriptor) ; 

puts ("before QlgUtime()"); 

QlgStat ((Qlg_Path_Name_T *) &path, &info); 
printf(" utime.file modification time is %ld\n", 


info.st_mtime); 
ubuf.modtime = 0; /* set modification time to Epoch */ 
time (&ubuf.actime) ; 
if (QlgUtime ((Qlg_Path_Name_T *)&path, é&ubuf) != 0) 
perror ("QlgUtime() error"); 
else { 
puts ("after QlgUtime()"); 


QlgStat ((Qlg_Path_Name_T *) &path, &info); 
printf(" utime.file modification time is %ld\n", 
info.st_mtime); 


} 
QlgUnlink((Qlg_Path_Name_T *) &path); 


Output: 


before QlgUtime () 

utime.file modification time is 749323571 
after QlgUtime () 

utime.file modification time is 0 
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»Perform Miscellaneous File System Functions 
(QPOFPTOS) API 


Required Parameter Group: 


1‘ Function type Char(*) 
2 Function extension 1 Char(**) 
3 Function extension 2 Char(**) 


Default Public Authority: *USE 


Threadsafe: No 


The Perform Miscellaneous File System Function (QPOFPTOS) API is used to perform a variety of file 
system functions. The first parameter defines the type of function that is requested. Other parameters are 
optional, depending on the selected function. The output from this API varies, based on the selected 
function. See the function descriptions for more details. 


Authorities and Locks 


To call this program you must have *SERVICE special authority, or be authorized to the Service Dump 
function of Operating System/400 through iSeries Navigator's Application Administration support. The 
Change Function Usage Information (QS YCHFUID) API, with a function ID of QIBM_SERVICE_DUMP, 


also can be used to change the list of users allowed to perform dump operations. 


Note: Adopted authority is not used. 


Required Parameter Group 


Required parameters vary according to the selected function. The selected function is identified by the first 
parameter on the call to the API. 


Function Type 
INPUT; CHAR(*) 


The desired file system function to perform. Valid values follow: 
(1) *DUMP 


Creates a general file system dump in a spooled file with file name "QSYSPRT" and with 
"QPOFDUMP" in the User Data field. No other parameters are required or supported when 
*DUMP is specified. 


(2) *DUMPALL 


Creates a variety of file system dumps in a single spooled file with file name "QS YSPRT" 
and with "QPOFDUMP" in the User Data field. The following table describes the optional 


parameter when *DUMPALL is specified. 


[Function —_[Function extension 1 {Function extension 2 [Description = 
*DUMPALL |Job number (CHAR 6) |(Not supported) Specifies the job that is 
dumped. If a job is not 
specified, the data is 
dumped for all jobs. If there 
are multiple jobs with the 
same number, the first one 
encountered will be 
dumped. 


(3) *DUMPLFS 


Creates a dump of logical file system data in a spooled file with file name "QSYSPRT" and 
with "QPOFDUMP" in the User Data field. The following table describes the optional 
parameter when *DUMPLES is specified. 


[Function [Function extension 1 |Function extension 2 [Description 

*DUMPLES |Job number (CHAR 6) |(Not supported) Specifies the job that is 
dumped. If a job is not 
specified, the data is 
dumped for all jobs. If there 
are multiple jobs with the 
same number, the first one 
encountered will be 
dumped. 


(4) *NFSFORCE 


Sets various values and modes for the network file system. The following table describes 
the required parameters when *NFSFORCE is specified. 


Function extension |Function extension 
Function 1 2 Description 


*NFSFORCE /V2 ON or OFF If ON, indicates version 2 
mounts only by the client. If 
QNFSMNTD is started 
afterwards, then server will 
permit version 2 mounts 
only. 


(5) *REBUILDDEVNULL 


Attempts to create the /dev/null and dev/zero character special files. If an existing dev/null 
or dev/zero object exists that is not a character special file, then the object is renamed to 
/dev/null.prv or dev/zero.prv. If /dev/null.prv or /dev/zero.prv exists, then it it renamed to 
/dev/null.prv.001 or /dev/zero.prv.001, /dev/null.prv.002 or /dev/zero.prv.002, and so on, 
until a name is found for the object. If 999 is exceeded and the rename cannot be done, the 
object is not renamed and an informational message is issued and the QPOFPTOS program 
completes successfully. No other parameters are required or supported when 
*REBUILDDEVNULL is specified. 


(6) *TRACE6ON or *TRACE6OFF 


*TRACEO6ON starts the logging of trace messages in the user job log for some network file 
system functions. *TRACE6OFF stops the logging of these messages. 


(7) *TRACESON or *TRACE8OFF 


*TRACE8ON starts the logging of trace messages to the QSYSOPR message queue for 
some network file system functions. *TRACE8OFF stops the logging of these messages. 


(8) *TRACEION or *TRACE9YOFF 


*TRACE9ON starts the collection of some network file system statistics and resets the 
statistics. *TRACE9OFF stops the collection of these statistics. 


(9) *DUMPNFSSTATS 


Creates a file system dump of network file system (NFS) statistics (both client and server) 
in a spooled file with file name "QSYSPRT" and with "QPOFDUMP" in the User Data 
field. The information dumped comes from a window of time specified with the 
*TRACE9ON/OFF function. No other parameters are required or supported when 
*DUMPNFSSTATS is specified. 


Function extension 1 
INPUT; CHAR(*) 
Function extension | is optional or required, based on the first parameter. Whenever it is valid, 


function extension | is described above along with a first parameter description. Function extension 
1 is valid when the first parameter is listed below: 


(1) *DUMPALL 
(2) *DUMPLFS 
(3) *NFSFORCE 


Function extension 2 
INPUT; CHAR(*) 


Function extension 2 is optional or required, based on the first parameter. Whenever it is valid, 
function extension 2 is described above along with a first parameter description. Function extension 
2 is valid when the first parameter is listed below: 


(1) *NFSFORCE 


Usage Notes 


If this API is called without the first parameter that is required, then message CPFBCS3 is issued to the 
caller. This message specifies a parameter that is not valid. To recover, the caller is pointed to the API 
documentation. 


Error Messages 


Message ID 
CPE3418 E 

CPF9872 E 

CPFAOAO E 
CPFA0D4 E 
CPDAOFF E 
CPFBCS3 E 
CPFBC54 E 


Examples 


Error Message Text 

Possible APAR condition or hardware failure. 

Program or service program &1 in library &2 ended. Reason code &3. 
Object name already exists. 

File system error occurred. Error number &1. 

Program not called. You need *SERVICE authority to call this program. 
Invalid parameter. 


Not authorized to call program. 


CALL QPOFPTOS *DUMP 


CALL QPOFPTOS (*DUMPALL '055229") 


CALL QPOFPTOS (*DUMPLES '055229') 


CALL QPOFPTOS (*NFSFORCE V2 ON) 


CALL QPOFPTOS *REBUILDDEVNULL 


CALL QPOFPTOS *TRACE6ON 


CALL QPOFPTOS *TRACE6OFF 


CALL QPOFPTOS *TRACE80N 


CALL QPOFPTOS *TRACE80FF 


CALL QPOFPTOS *TRACE9ON 


CALL QPOFPTOS *TRACE9OFF 


CALL QPOFPTOS *DUMPNFSSTATS 


% 
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QpoiCvtPathToQSYSObjName()-- Resolve 
Integrated File System Path Name into QSYS 
Object Name 


Syntax 


#include <qp0Olstdi.h> 


void Qp01lCvtPathToQSYSOb jName ( 
Qlg_Path_Name_T *path_name, 
void *qsys_info, 
char format_name[8], 
uint bytes_provided, 
uint desired_CCSID, 
void *error_ code); 


Threadsafe: Conditional; see Usage Notes. 


2The Qp0ICvtPathToQSYSObjName() function resolves a given integrated file system path name into 
the four-part QSYS.LIB or independent ASP QSYS.LIB file system name. The primary three parts of the 
path name are the following components: library, object, and member. The fourth part of the path name is a 
character representation of the ASP associated with the object, or the independent ASP name. This depends 
on whether the path refers to an object in the QSYS.LIB file system or and object in an independent ASP 
QSYS.LIB file system. If the path contains symbolic links, they will be resolved. If, after symbolic links 
have been resolved, the path does not refer to an object that could be in either the QS YS.LIB file system or 
an independent ASP QSYS.LIB file system, the API will return with the error message CPFAODB 
indicated in the error_code structure. Note that the API does not verify that the object exists.“ 


The API also handles wildcard (*) characters in the path name. If the name or type of a library, object, or 
member is just an asterisk, *ALL is returned as the name or the type. If an asterisk is part of a library, 
object, or member name, a name containing an asterisk is returned. For example if the following path name 
is passed in: 


/qsys.lib/test*.file/*.* 


the API will return: 
e Library name: QSYS 
e Library type: *LIB 
e Object name: TEST* 
e Object type: *FILE 
e@ Member name: *ALL 
e Member type: *ALL 
e ASP name: *SYSBAS* 


Note that path name components that follow one containing a wildcard character are ignored. 


If less than 8 bytes are supplied for the error_code structure, errors will cause an exception to be returned to 
the caller. 


Parameters 


path_name 


(Input) The path name that refers to the QSYS.LIB #*or independent ASP QSYS.LIB file system 
“object. The path name must refer to an object on the local file system; this API does not 
recognize file system objects accessed remotely. This path name is in the Qlg_Path_Name_T 
format. For more information on this structure, see Path name format. If the path_name parameter 


is NULL or points to invalid storage, a CPFAOCE error message is returned. 
qsys_info 
(Output) A pointer of type void * that refers to a structure that contains the object name. The format 


of the data returned is specified by the format_name parameter. If the qsys_info parameter is NULL 
or points to invalid storage, a CPF24B4 error message is returned. 


format_name 


(Input) An 8-byte character array that indicates how the data will be formatted in the gsys_info 
parameter that is returned. The format is as follows: 


QSYS0100 


For the format of this structure, see the section Returned Data Format. 


If the format_name parameter is NULL or points to invalid storage, a CPF24B4 error message is 
returned. 


bytes_provided 


(Input) The number of bytes of data provided in the structure referred to by the gsys_info 
parameter. This value must be at least 8, or a CPF3C24 error message will be returned. 


desired_CCSID 


(Input) The CCSID the returned object names and types should be converted to. If the value of this 
parameter is 0, the object names and types will be returned in the job CCSID. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Authorities 


Note: Adopted authority is not used. 
Authorization Required for the Qp0IC vtPathToQSYSObjName() API 


Authority 
Object Referred to Required |Message ID 


[Each directory, preceding the last component, in the path name. *X |CPFA09C 


Object in the QSYS.LIB #*or independent ASP QSYS.LIB “file system that the | None |None 
path name refers to. 


Returned Data Format 


The following table describes the format of the data returned in the gsys_info parameter if the QSYSO100 
format is specified. For details on the fields of the structure, see the section Field Descriptions. 


[Offset 
sae Hex |Type Field 


rs | 8 |BINARY@) |CCsiD_ow —~—~SCS~*~S 
| 12 [| C  |[CHAR@8) [LibName 9 
| 60 | 3C |[CHAR@8)  |ObiName ——— 
| 108 [ 6C |CHAR(28) 9 [MbrName ——— 


Field Descriptions 


“ASP Name. The path name component that represents the ASP name, if part of the path, or the ASP that 
the path is associated with. For paths that refer to objects in independent ASP QSYS.LIB file systems, this 
will be the name of the ASP device description object. For paths that refer to objects in the QSYS.LIB file 
system, the value of ASP Name will be *SYSBAS.%& 


Bytes_Available. The total number of bytes required to hold all of the data available in the gsys_info 
parameter. 


Bytes_Returned. The number of bytes actually returned in the caller's buffer for the gsys_info parameter. 


CCSID_Out. The CCSID that the returned text is in. This may be different than the desired_CCSID if 
conversion failed. The text is internally normalized, then converted to the desired CCSID. If this conversion 
from the normalized form does not succeed, the text will be returned in the CCSID of the normalized form. 


Lib_Name. The name of the library that the path name refers to. This field is NULL terminated. 


Lib_Type. The type of the object, beginning with an * (asterisk). This field will return either *LIB or 
*ALL. This field is NULL terminated. 


Mbr_Name. The name of the member that the path name refers to. This field is NULL terminated, and 
could be all NULL (all x'00'). 


Mbr_Type. The type of the member that the path name refers to. This field is NULL terminated. This field 
will contain *MBR, *ALL, or all NULL (all x'00'). 


Obj_Name. The name of the object that the path name refers to. This field is NULL terminated, and could 
be all NULL (all x'00’). 


Obj_Type. The type of the object that the path name refers to. This field is NULL terminated. This field 
could contain an object type (for example *FILE), *ALL, or be NULL (all x'00'). 


The Lib_Name, Lib_Type, Obj_Name, Obj_Type, Mbr_Name, and Mbr_Type fields of the 
QpO0l_QSYS_Info_t structure will be filled in as appropriate. 


If the object that the path name refers to is a library (*LIB), then the lib_name and lib_type fields will 
contain that library name and *LIB, respectively, and the Obj_Name and Mbr_Name fields will be NULL 
(all x'00'). 

If the object name is not an *FILE object with members, then the Mbr_Name field is NULL (all x'00'). 


If the object name contains quoted strings, the characters within the strings will not be converted to 
uppercase. 


Error Conditions 


None. 


Error Messages 


CPE3101 E I/O exception non-recoverable error. 

CPE3101 E I/O exception non-recoverable error. 

CPE3418 E Possible APAR condition or hardware failure. 
CPE3474 E Unknown system state. 

CPF24B4 E Severe error while addressing parameter list. 
CPF3BF6 E Path type value not valid. 

CPF3C24 E Length of the receiver variable is not valid. 
CPF3CF1 E Error code parameter not valid. 

CPF9872 E Program &1 in library &2 ended. Reason code is &3. 
CPFA092 E Path name not converted. 

CPFAO9CE Not authorized to object. Object is &1. 
CPFAO9EE = Object in use. Object is &1. 

CPFAO9F E Object damaged. Object is &1. 

CPFAOA1E — An input or output error occurred. 

CPFAOA2E _ Information passed to this operation was not valid. 
CPFAOA3 E Path name resolution causes looping. 

CPFAOA7E Path name too long. 

CPFAOA8 E Operation not allowed in a job running multiple threads. 
CPFAOA9E = Object not found. Object is &1. 

CPFAOAA E — Error occurred while attempting to obtain space. 
CPFAOAD E — Function not supported by file system. 
CPFAOB1E — Requested operation not allowed. Access problem. 
CPFAOCOE ~ Buffer overflow occurred. 

CPFAOCIE  CCSID &1 not valid. 

CPFAOCE E — Error occurred with path name parameter specified. 
CPFAOD4E _ File system error occurred. Error number &1. 
CPFAOD9 E — Character string not converted. 

CPFAODB E = Object not a QSYS.LIB object. Object is &1. 
CPFAODD E Function was interrupted. 


CPFAOEOE File ID conversion of a directory failed. 

CPFAOE1E The file ID table is damaged. 

CPFAOE2E — System unable to establish a communications connection to a file server. 
CPFAOE4E = The communications connection with the file server was abnormally ended. 
CPFAOES E The communications connection with the file server was abnormally ended. 
CPFAOE6E = Object handle rejected by file server. 

CPFAOE7E — System cannot establish a communications connection with a file server. 
CPFAICSE = Object is a read only object. Object is &1. 


Usage Notes 


1. This API will fail and return the error message CPFAOA8 when all the following conditions are 
true: 


oO Where multiple threads exist in the job. 


oO The object this function is operating on resides in a file system that is not threadsafe. Only 
the following file systems are threadsafe for this function: 


m Root 

m QOpenSys 

m User-defined file system 

mw QSYS.LIB 

m “Independent ASP QSYS.LIB 


2. #This API ignores trailing blank spaces at the end of a path name. 
For example, if the path name is 


"/qsys.lib/fred.lib/foo.file/abc.mbr " 


the trailing blank spaces will be ignored. Thus, the above path name is equivalent to 


"/qsys.lib/fred.lib/foo.file/abc.mbr" 
< 


Related Information 


e The <qp0lIstdi.h> file (see Header Files for UNIX-Type Functions) 


e@ QleQp0lCvtPathToQS YSObjName()-- Resolve Integrated File System Path Name into QSYS 
Object Name 


Example 


The following example program gets the three-part QSYS name from an integrated file system path name 
passed to it. 


#include <qpOlstdi.h> /* For Qp0lCvtPathToQSYSObjName avs 
/* type Qp0l_OQSYS_Info_t */ 
[fe type Qlg_Path_Name_T * / 
#include <qusec.h> /* For type Qus_EC_T * / 


#include <stdlib.h> 
#include <stdio.h> 


int main () 


[RK KK KR KK KK KK KK I I KK KK / 
/* Declaration of path_name parameter * / 
[RK KKK KK KK KK I KK I I I I KK KK / 
char path_info_array[500]; 

Qlg_Path_Name_T *path_name; 

const char fname[] = 
"/aqsys.lib/jerold.lib/qcesrc.file/testconv.mbr"; 

const char US_const[] = "US"; 

const char Language_const[] = "ENU"; 

const char Path_Name_Del_const[] = "/"; 


[RK KKK KK KK KK KI I I KK KK  / 


/* Declaration of qsys_info parameter af 
[RK KK KR KK KK KK KK KE I I II I KK KK / 


Qp0l_QSYS_Info_t qsys_info; 


[BRK KKK KK KKK I KI I KI KK KK / 


/* Declaration of format_name parameter */ 
[RK KKK KK KK KK KK KI I I KK KK / 
char format_name[8] = "QSYS0100"; 


[BRK KKK KK KK KK I KI I I I KK KK KK / 


/* Declaration of bytes_provided parameter * 
[BRK KK KK KK KK KI I I I I I KK KK / 


uint bytes_provided; 


[BRK KKK KK KR KK KE KI I I IE I KK KK / 


/* Declaration of desired_CCSID parameter. */ 
[BRK KKK KK KK KK KI I I I I KK KK / 


uint desired_CCSID; 


[BRK KKK KK KK KK KI I I I I I KK KK / 


/* Declarations for error_code parameter a 
[RK KKK KK KK KK KE KI I I I KK KK / 


Qus_EC_t error_code; 
char error_string[8]; 


[RK KKK KK KK KK KI I I I I KK KK  / 


/* Initialize path_name parameter * 
[BRK KKK KK KK KK KI I I I KK KK / 


memset (path_info_array, 0, sizeof (path_info_array) ); 
path_name = (Qlg_Path_Name_T *) path_info_array; 


path_name->CCSID = 37; 
memcpy (path_name->Country_ID, US_const, 2); 
memcpy (path_name->Language_ID, Language_const, 3); 
path_name->Path_Type = 0; 
path_name->Path_Length = strlen(fname) ; 
memcpy (path_name->Path_Name_Delimiter, Path_Name_Del_const, 1); 
memcpy ( &(((char *) path_name) [sizeof (Qlg_Path_Name_T)]), 
fname, 
strlen(fname) ); 


[BRK KKK KK KKK KK KE I I I KK KK / 


/* Initialize qsys_info parameter */ 
[RK KKK RK KKK I I I KK KK / 


/* No initialization requirements for this parameter. */ 


[BRK KKK KK KKK I I I EI I RK KK / 


/* Initialize format_name parameter */ 
[RK KKK KK KK KK KK KI I KK KK / 


/* No additional initialization required. */ 


[RK KKK KK KK KK KK I I KK KK / 


/* Initialize bytes_provided parameter. */ 
[RK KKK KK KR KK KK KI I I I KK KK / 


bytes_provided = sizeof (Qp01_OQSYS_Info_t); 


[BRK KKK KK KK KK KK I I KI I KK KK / 


/* Initialize desired_CCSID parameter. */: 
[RK KKK KK KK KK KI I I I I I KK KK / 


desired_CCSID = 37; 


[RK KKK RK KKK I KE I I II I KK KK / 


/* Initialize error_code param */ 
[RK KKK KK KK KK KI I KK KK / 
memset (&error_code, 0, sizeof(error_code) ); 
error_code.Bytes_Provided = sizeof (error_code) ; 


[BRK KKK KK KK KK KI I I I I KK KK I / 


/* Call API * / 
[BRK KKK KK KK KK KK I I KK KK / 
QpOlCvtPathToQSYSObjName (path_name, 

QOSYS.LIB_info, 

format_name, 

bytes_provided, 

desired_CCSID, 

&error_code) ; 


if (error_code.Bytes_Available > 0) 


{ 


[RK KKK RK KR KK I I I EE I KK KK KK / 


/* Error occurred. * / 
[BRK KKK RK KK KR I KI I KK KK / 


printf ("Error occurred: "); 
memcpy (error_string, error_code.Exception_Id, 7); 


error_string[7] = '\0O'; 
printf ("Ss\n", error_string); 


printf ("Bytes available in error code structure: %d.\n", 
error_code.Bytes_Available) ; 
exit (1); 

} 


[BKK KKK KKK KR KKK KK KKK KK KK RK KK RK KK ee / 


/* API returned successfully. * / 
[KKK KKK KK KKK KK KK RK KK KR KK KK KK Re  / 


printf ("Library name: %s\n", qsys_info.Lib_Name) ; 
printf ("Library type: %s\n", qsys_info.Lib_Type); 
printf ("Object name: %s\n", qsys_info.Obj_Name) ; 
printf ("Object type: %s\n", qsys_info.Obj_Type) ; 
printf ("Member name: %s\n", qsys_info.Mbr_Name) ; 
printf ("Member type: %s\n", qsys_info.Mbr_Type) ; 
printf ("Asp name: s\n", qsys_info.Asp_Name) ; 


<4 exit (0); 
} 


Output: 


Library name: JEROLD 
Library type: *LIB 
Object name: QCSRC 
Object type: *FILE 
Member name: TESTCONV 
Member type: *MBR 
Asp name: *SYSBAS 
x 


API introduced: V4R3 


Top | UNIX-Type APIs | APIs by category 


Perform File System Operation (QPOLFLOP) 
API 


Required Parameter Group: 


File System Operation Binary(4) 
Input Buffer Char(*) 
Length of input buffer Binary(4) 
Output Buffer Char(*) 


Length of output buffer Binary(4) 
Error code Char(*) 


Default Public Authority: *USE 


Threadsafe: No 


The Perform File System Operation (QPOLFLOP) API performs miscellaneous file system operations. 


Authorities and Locks 


The authorities required vary for each operation: 
(1) QPOL_RETRIEVE_NETGROUP_FILE_ENTRIES 
o The user must have execute (*X) data authority to the /etc directory (if it exists). 


o The user must have read (*R) data authority to the /etc/netgroup file (if it exists). 


(2) QPOL_WRITE_NETGROUP_FILE_ENTRIES 


o The user must have write and execute (*WX) data authority to the /etc directory (if it 
exists). 


o The user must have read and write (*RW) data authority to the /etc/netgroup file (if it 
exists). 


Note: Adopted authority is not used. 


Required Parameter Group 


The following parameters are required. 
File system operation 
INPUT; BINARY(4) 


The desired file system operation to perform. 


You can specify one of the following operations: 


(1) QPOL_RETRIEVE_NETGROUP_FILE_ENTRIES 


Returns information about all netgroup definitions currently defined in the /etc/netgroup 
file. 


(2) QPOL_WRITE_NETGROUP_FILE_ENTRIES 


Recreates the /etc/netgroup file with only the entries provided. 


Input buffer 
INPUT; CHAR(*) 
Information that is required for a given file system operation. The input buffer parameter should be 
set as follows: 
(1) QPOL_RETRIEVE_NETGROUP_FILE_ENTRIES 
NULL (no input buffer is required). 


(2) QPOL_WRITE_NETGROUP_FILE_ENTRIES 


FLOP0200 structure containing the new netgroup entries. For a detailed description of this 
structure, see Format of FLOP0200 Structure. 


Length of input buffer 
INPUT;BINARY(4) 


The length of the input buffer provided. The length of the input buffer parameter may be specified 
up to the size of the input buffer area specified by the user program. The length of the input buffer 
should be 0 when the input buffer is NULL. 


Output buffer 
OUTPUT; CHAR(*) 


Information that is provided by a given file system operation. The output buffer parameter should 
be set as follows: 


(1) QPOL_RETRIEVE_NETGROUP_FILE_ENTRIES 
FLOPO100 structure containing enough space to hold all netgroup entries in the 
/etc/netgroup file. For a detailed description of this structure, see FLOP0100 Structure 
Description. No partial entries will be returned. To determine if all of the entries were 
returned, the following semantics will be used: 


m If the /etc/netgroup file has no entries defined, bytes available and bytes returned 
will both be set to 12. 


m If the /etc/netgroup file has at least one entry defined, then the bytes available will 
be greater than 12. 


am If all of the defined entries in the /etc/netgroup file could not be returned, then the 
bytes available will not have the same value as bytes returned. 


For example, if the /etc/netgroup file is empty, then bytes available and bytes returned 
would both be equal to 12. For a different example, if the /etc/netgroup file is not empty, 
but the length of the output buffer is less than what is required to hold all entries in the 
/etc/netgroup file, then bytes available would be greater than 12 and bytes returned would 
be set to 12. 


(2) QPOL_WRITE_NETGROUP_FILE_ENTRIES 
NULL (no output buffer is required). 


Length of output buffer 
INPUT; BINARY(4) 
The length of the output buffer provided. The length of the output buffer parameter may be 


specified up to the size of the output buffer area specified by the user program. The length of the 
output buffer should be 0 when the output buffer is NULL. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Output Buffer Description 


The following table describes the order and format of the data returned in the output buffer. For a detailed 
description of each field, see Field Descriptions. 


FLOP0100 Structure Description 


This structure is used to return netgroup definitions taken from the /etc/netgroup file. 


| Offset 
| D c | Hex |Type Field 


| pao i CSCS 
[| 4 | 4  |BINARY() [Bytesavailable = = = == 
a BIN HERI [Number of netgroupentries 
BING) [lasshal sigsar sage 
BINARY(4)  [Displacementtomembernames 
BINARY(4) [Numberofmembernames 
CHAR(*) [Netgroupname——sss—‘—sSCS 
[BINARY(4) {Length of member nameentry = 
BINARY(4) [Membername status 
[BINARY(4) [Lengthofmembername =———s—S 
[CHAR(*) [Membername —s—‘“‘“—~—<‘“‘“‘it~™*”s 


Input Buffer Description 


The following table describes the order and format of the data given in the input buffer parameter. For a 
detailed description of each field, see Field Descriptions. 


Format of FLOP0200 Structure 


| Offset 
ae Hex |Type Field 


BINARY(4) Number of netgroup entries 
BINARY(4) Length of netgroup entry 
BINARY(4) Length of netgroup name 
BINARY(4) Displacement to member names 
BINARY(4) Number of member names 
CHAR(*) Netgroup name 

These fields BINARY(4) Length of member name entry 
repeat for each BINARY(4) Member name status 

member name in = 

the netgroup BINARY(4) Length of member name 
entry. CHAR(*) Member name 


Field Descriptions 


Bytes available. The number of bytes of data available to be returned to the user in the output buffer. If all 
data is returned, bytes available is the same as the number of bytes returned. If the receiver variable was not 
large enough to contain all of the data, this value is set based on the total number of entries in the 
/etc/netgroup file. 

Bytes returned. The number of bytes of data returned to the user in the output buffer. 


Displacement to member names. The offset (in bytes) from the beginning of the netgroup entry to the 
member names in the netgroup entry. 


Length of entry. The length (in bytes) of the current netgroup entry. The length can be used to access the 
next entry. 


Length of member name. The length (in bytes) of the member name. 

Length of member name entry. The length (in bytes) of this member name entry. 
Length of netgroup name. The length (in bytes) of the netgroup name. 

Member name. The member name. This is assumed to be in the CCSID of the job. 


Member name status. Describes the type of member name. Possible values follow: 
(1) QPOL_MEMBER_IS_A_HOST_NAME 


The member name refers to an individual host name. 


(2) QPOL_MEMBER_IS_A_NETGROUP_NAME 


The member name refers to a netgroup name. 


(3) QPOL_MEMBER_IS_AN_IP_ADDRESS 


The member name refers to an IP address in the form xxx.xxx.xxx.xxx (for example 123.4.56.78). 
Netgroup name. The netgroup name. This is assumed to be in the CCSID of the job. 
Number of member names. The number of member names in the netgroup entry. 


Number of netgroup entries. The number of complete entries. A value of zero is used if there are no valid 
entries for the /etc/netgroup file or if the file does not exist. 


Usage Notes 


The include file for this API is QPOLFLOP. 


If none of the required parameters are passed to this API, then message CPFB41F will be issued to the 
caller. This message lists all of the file operations currently available to the QPOLFLOP API. 


WARNING - When the (2) QPOL_WRITE_NETGROUP_FILE_ENTRIES file system operation is 
requested, the existing /etc/netgroup file will be completely rewritten resulting in a loss of the previous 
contents of the file. 


A netgroup is a way of defining one name (the netgroup name) to represent many other names. The names 
contained within a netgroup definition are called 'members' of that netgroup. A netgroup member can be 
either the name of a host system, the name of another netgroup, or an IP address. Netgroup definitions are 
stored in the /etc/netgroup file and are commonly used by the Network File System (NFS) support when a 
large group of host systems require common NFS access semantics. 


Error Messages 


CPFAOD4E _ File system error occurred. 

CPE3418 E Possible APAR condition or hardware failure. 

CPF3C90 E Literal value cannot be changed. 

CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 

CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


API introduced: V4R3 


Top | UNIX-Type APIs | APIs by category 


Qp0!lGetAttr()--Get Attributes 


Syntax 


#include <Qp0Olstdi.h< 

int Qp01GetAttr 
(Qlg_Path_Name_T *Path_Name, 
Qp0l_AttrTypes_List_t *Attr_Array_ptr, 
char *Buffer_ptr, 
uint Buffer_Size_Provided, 
uint *Buffer_Size_Needed_ptr, 
uint *Num_Bytes_Returned_ptr, 
uint Follow_Symlnk, ...)j; 


Service Program Name: QPOLLIB2 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The Qp01GetAttr() function gets one or more attributes, on a single call, for the object that is referred to by 
the input Path_Name. The object must exist, the user must have authority to it, and the requested attributes 
must be supported by the specific file system. For each requested attribute that is not supported by the file 
system, Qp0IGetAttr() returns zero in the Size of attribute data field, pointed to by the Buffer_ptr parameter, 
for that attribute. 


Qp0lGetAttr() either returns the attributes of the symbolic link, or returns the attributes of the object that the 
symbolic link names. This depends upon the value of the Follow_Symlink parameter. 


Qp01GetAttr() returns all times in seconds since the Epoch so that they are consistent with UNIX-type APIs. 
The Epoch is the time 0 hours, 0 minutes, 0 seconds, January 1, 1970, Coordinated Universal Time. If the 
OS/400 date is set prior to 1970, all time values are zero. 


Parameters 


Path_Name 


(Input) The path name of the object for which attribute information is returned. This path name is in 
the Qlg_Path_Name_T format. For more information on this structure, see Path name format. 


Attr_Array_ptr 


(Input) A pointer to a structure listing the requested attributes returned for the object identified by the 
Path_Name parameter. Each entry in the array identifies an attribute, by a constant value, that 
Qp01GetAttr() returns. The number of requested attributes field must equal the total number of 
constants. If the Attr_Array_ptr is NULL or if the Number of requested attributes field is zero, 
Qp0lGetAttr() returns all the attributes that the API supports that are available for the object. The 
format of this parameter follows. 


[Attribute array pointer 
| Offset | 


| Dec Hex |Type |Field 
| 0 0 [BINARY (4) Number of requested attributes 


4 4 ARRAY (*) of | |Array of attribute constants 
BINARY (4) 


Array of attribute constants. A list of predefined constants, each identifying a requested attribute. 
Qp01Getattr() also returns one of these constants in the Attribute identification field, pointed to by 
the Buffer_ptr parameter. The constant must be used to identify the returned attribute because the 
attributes are returned in any order. Note that the Size of attribute data field, pointed to by the 
Buffer_ptr parameter, contains the total size of data that Qp0IGetattr() returns for the constants in this 
array. Valid values, and sizes of the returned attributes, follow: 


0 


QPOL_ATTR_OBJTYPE: (CHAR(10)) The object type. See Control Language (CL) 
information in the iSeries Information center for descriptions of all iSeries object types. 


QPOL_ATTR_DATA_SIZE: (UNSIGNED BINARY(4)) The size in bytes of the data in this 
object. This size does not include object headers or the size of extended attributes associated 
with the object. If this attribute is requested and the size cannot be represented in a 
BINARY (4) data type, Qp0IGetAttr() fails with errno [EOVERFLOW]. Refer to 
QPOL_ATTR_DATA_SIZE_64 for objects whose data sizes are greater than BINARY(A4). 


QPOL_ATTR_ALLOC_SIZE: (UNSIGNED BINARY(4)) The number of bytes that have 
been allocated for this object. If this size cannot be represented in a BINARY (4) data type, 
Qp0lGetAttr() fails with errno [EOVERFLOW]. Refer to QPOL_ATTR_ALLOC_SIZE_64 
for objects whose allocated sizes are greater than BINARY(4). 


QPOL_ATTR_EXTENDED_ATTR_SIZE: (UNSIGNED BINARY(4)) The total number of 
extended attribute bytes. 


QPOL_ATTR_CREATE_TIME: (UNSIGNED BINARY ‘(4)) The time the object was 
created. 


QPOL_ATTR_ACCESS_TIME: (UNSIGNED BINARY (4)) The time that the object's data 
was last accessed. 


QPOL_ATTR_CHANGE_TIME: (UNSIGNED BINARY‘(4)) The time that the object's data 
or attributes were last changed. 


QPOL_ATTR_MODIFY_TIME: (UNSIGNED BINARY(4)) The time that the object's data 
was last changed. 


QPOL_ATTR_STG_FREE: (CHAR(1)) Whether the object's data has been moved offline, 
freeing its online storage. Valid values are: 


x'00' QPOL_SYS_NOT_STG_FREE: The object's data is not offline. 


x'01'’ QPOL_SYS_STG_FREE: The object's data is offline. 
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QPOL_ATTR_CHECKED_OUT: Whether an object is checked out or not. When an object 
is checked out, other users can read and copy the object. Only the user who has the object 
checked out can change the object. The checkout format is defined in the QpOlstdi.h header 
file as data type Qp0l_Checkout_t, and is described in the following table. 


Checkout Format 


| Offset 
| Dec | Hex |Type Field 


0 0 |CHAR(1) Flag indicating whether an object is 
checked out 
| 1 | 1 |CHAR(10) [User to whom checked out 


| 11 | B- |CHAR(1) [Reserved 
| 12 | C |BINARY(4) [Time checked out 


Flag. An indicator as to whether an object is checked out. Valid values are: 
x'00' QPOL_NOT_CHECKED_OUT: The object is not checked out. 
x'01'’ QPOL_CHECKED_OUT: The object is checked out. 


Reserved. A reserved field. This field must be set to binary zero. 


Time checked out. The time the object was checked out. This field represents the number of 
seconds since the Epoch. 


User to whom checked out. The user who has the object checked out. This field is blank if 
it is not checked out. 


QPOL_ATTR_LOCAL_REMOTE: (CHAR(1)) Whether an object is stored locally or stored 
on a remote system. The decision of whether a file is local or remote varies according to the 
respective file system rules. Objects in file systems that do not carry either a local or remote 
indicator are treated as remote. Valid values are: 


x'0l' QPOL_LOCAL_OBJ: The object's data is stored locally. 


x'02' QPOL_REMOTE_OBJ: The object's data is on a remote system. 


QPOL_ATTR_AUTH: The public and private authorities associated with the object. 


When the QPOL_ATTR_AUTH attribute is requested, the attribute data is returned in the 
buffer in the following format. This format is defined in header file QpOlstdi.h as data type 
QpOl_Authority_General_t. 


General Authority Format 


| Offset 
| Dec | Hex |Type Field 


| 48 | 30 |BINARY(4) [Size of user entry field entry 
| 52 | 34. |CHAR(12) [Reserved 
| | ARRAY(*) [Array of users 


Array of users. The names and authorities of the users who are authorized to use the object. 


Authorization list name. The name of the authorization list that is used to secure the named 
object. The value *NONE indicates that no authorization list is used in determining 
authority to the object. 


Number of users. The number of users that are authorized to the object. This is the number 
of users returned in the array of users. 


The QFileSvr.400 file system returns zero for the Number of users and zero for the Offset to 
array of users. If a primary group is specified, the Network File System (NFS) returns one 
for the Number of users. 


Object owner. The name of the user profile that is the owner of the object or the following 
special value: 


*NOUSRPRF This special value is used by the Network File System to indicate that 
there is no user profile on the local iSeries server with a user ID (UID) 
matching the UID of the remote object. 


Offset to array of users. The offset to the names and authorities of the users who are 
authorized to use the object. This offset is relative to the offset of the QPOL_ATTR_AUTH 
attribute within the buffer pointed to by the Buffer_ptr parameter. 


Primary group. The name of the user profile that is the primary group of the object or the 
following special values: 


*NONE The object does not have a primary group. 
*NOUSRPRF This special value is used by the Network File System to indicate that 


there is no user profile on the local server with a group ID (GID) 
matching the GID of the remote object. 


Reserved. A reserved field. This field must be set to binary zero. 
Size of user entry field entry. The number of bytes returned for each user. 
When the QPOL_ATTR_AUTH attribute is requested, the array of users is returned in the 


buffer in the following format. This format is defined in header file QpOlstdi.h as data type 
QpOl_Authority_Users_t. 


Data and Object Authority Format 


| Offset 
| Dec | Hex |Type Field 


| 35 | 23 |CHARC) [Read 
[36 [24 CHARM) |Add S~S 
[37_| 25 |CHARG) [Update —S~S~S 
| 38 | 26 |CHAR(1) [Delete 
[40 | 28 |CHAR() [Excude ~~SCSCS~S~S 


Add (*ADD). Authority to add entries to the object. Valid values are: 


O The user does not have add data rights. 


I The user does have add data rights. 


Delete (*DELETE). Authority to remove entries from the object. Valid values are: 


O The user does not have delete data rights. 


I The user does have delete data rights. 


Execute (“EXECUTE). Authority to run a program or search a library or directory. Valid 
values are: 


0 The user does not have execute data rights. 


I The user does have execute data rights. 


Exclude (*EXCLUDE). The user is prevented from accessing the object. Valid values are: 
O The user does not have exclude data rights. 


I The user does have exclude data rights. 


Object alter (“*OBJALTER). Authority to change the attributes of an object, such as 
adding or removing triggers for a database file. Valid values are: 


0 The user does not have alter object rights. 


I The user does have alter object rights. 


Object existence (*“OBJEXIST). Authority to control the object's existence and ownership. 
Valid values are: 


0 The user does not have object existence rights. 


I The user does have object existence rights. 


Object management (*OBJMGT). Authority to specify security, to move or rename the 
object, and to add members if the object is a database file. Valid values are: 


O The user does not have object management rights. 


I The user does have object management rights. 


Object operational (*“OBJOPR). Authority to look at the object's attributes and to use the 
object as specified by the data authorities that the user has to the object. Valid values are: 


0 The user does not have object operational rights. 


I The user does have object operational rights. 


Object reference (*OBJREF). Authority to specify the object as the first level in a 
referential constraint. Valid values are: 


0 The user does not have object reference rights. 


I The user does have object reference rights. 


Read (*READ). Authority to access the contents of the object. Valid values are: 
O The user does not have read data rights. 


I The user does have read data rights. 


Reserved. A reserved field. This field must be set to binary zero. 


Update (*UPDATE). Authority to change the content of existing entries in the object. Valid 
values are: 


0 The user does not have update data rights. 


I The user does have update data rights. 


User data authority. The operation, use, or access that the user has to an object. Valid 
values follow: 


*RWX Allows all operations on the object except those that are limited to the 
owner or controlled by the object rights. 


*RW Allows access to the object attributes and allows the object to be changed. 
The user cannot use the object. 


*WX Allows use of the object and allows the object to be changed. The user 
cannot access the object attributes. 

*R Allows access to the object attributes. 

*W Allows the object to be changed. 

*X Allows the use of the object. 


*EXCLUDE All operations on the object are prohibited. 
*NONE Displayed by the system when the user does not have any data authorities. 


USER DEF _ Displayed by the system when the specific data authorities do not match 
any of the predefined data authority levels above. 
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User name. The name of a user authorized to use the object. This may be the name of the 
user profile or one of the following special values: 


*NOUSRPRF The authorities of either the owner or the primary group of the object for 
which the profile name could not be determined. This value is used by 
the Network File System only. It indicates that the user ID (UID) or the 
group ID (GID) for the remote object does not match any profile on the 
local iSeries server with that UID or GID. 


*NTWIRF The authorities of the NetWare Inherited Rights Filter for the object. This 
value is only used by the QNetWare file system. 


*NTWEFF The NetWare effective rights to the object. This value is only used by the 
QNetWare file system. 


*PUBLIC The authorities of users who are not specifically named and who are not 
in the object's authorization list. 


QPOL_ATTR_FILE_ID: (CHAR(16)) An identifier associated with the referred to object. A 
file ID can be used with Qp0IGetPathFromFileIDQ to retrieve an object's path name. The 


file ID is defined in header file QpOlstdi.h as data type QpOIFID_t. 
QPOL_ATTR_ASP: (BINARY(2)) The auxiliary storage pool in which the object is stored. 


QPOL_ATTR_DATA_SIZE_64: (UNSIGNED BINARY(8)) The size in bytes of the data in 
this object. This size does not include object headers or the size of extended attributes 
associated with the object. QPOL_ATTR_DATA_SIZE may be used for objects whose data 
size can be represented in a BINARY(4) data type. 


QPOL_ATTR_ALLOC_SIZE_64: (UNSIGNED BINARY(8)) The number of bytes that 
have been allocated for this object. QPOL_ATTR_ALLOC_SIZE may be used for objects 
whose allocated size can be represented in a BINARY(4) data type. 


QPOL_ATTR_USAGE_INFORMATION: Fields indicating how often an object is used. 
Usage has different meanings according to the specific file system and according to the 
individual object types supported within a file system. Usage can indicate the opening or 
closing of a file or can refer to adding links, renaming, restoring, or checking out an object. 
The usage information format is defined in the QpOlstdi.h header file as data type 
QpOl_Usage_t and is shown in the following table. 


QOp0l_Usage_t 


| Offset 
Les =e |e Hex |Type Field 


Days used count. The number of days an object has been used. Usage has different 
meanings according to the specific file system and according to the individual object types 
supported within a file system. Usage can indicate the opening or closing of a file or can 
refer to adding links, renaming, restoring, or checking out an object. This count is 
incremented once each day that an object is used and is reset to zero by calling the 
QpolSetAttr(¢) API. 


Last used date. The number of seconds since the Epoch that corresponds to the date the 
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object was last used. This field is zero when the object is created. If usage data is not 
maintained for the OS/400 type or the file system to which an object belongs, this field is 
zero. 


Reserved. A reserved field set to binary zeros. 


Reset date. The number of seconds since the Epoch that corresponds to the date the days 
used count was last reset to zero (0). This date is set to the current date when the 
QpOlSetAttr() API is called to reset the Days used count to zero. 


QPOL_ATTR_PC_READ_ONLY: (CHAR(1)) Whether the object can be written to or 
deleted, have its extended attributes changed or deleted, or have its size changed. Valid 
values are: 


x'00' QPOL_PC_NOT_READONLY: The object can be changed. 
x'0l' QPOL_PC_READONLY: The object cannot be changed. 


QPOL_ATTR_PC_HIDDEN: (CHAR(1)) Whether the object can be displayed using an 
ordinary directory listing. 


x'00' QPOL_PC_NOT_HIDDEN: The object is not hidden. 
x'01' QPOL_PC_HIDDEN: The object is hidden. 


QPOL_ATTR_PC_SYSTEM: (CHAR(1)) Whether the object is a system file and is 
excluded from normal directory searches. 


x'00' QPOL_PC_NOT_SYSTEM: The object is not a system file. 


x'0l' QPOL_PC_SYSTEM: The object is a system file. 


QPOL_ATTR_PC_ARCHIVE: (CHAR(1)) Whether the object has changed since the last 
time the file was examined. 


x'00' QPOL_PC_NOT_CHANGED: The object has not changed. 
x'01' QPOL_PC_CHANGED: The object has changed. 


QPOL_ATTR_SYSTEM_ARCHIVE: (CHAR(1)) Whether the object has changed and 
needs to be saved. It is set on when an object's change time is updated, and set off when the 
object has been saved. 


x'00' QPOL_SYSTEM_NOT_CHANGED: The object has not changed and does not 
need to be saved. 


x'0Ol' QPOL_SYSTEM_CHANGED: The object has changed and does need to be saved. 


QPOL_ATTR_CODEPAGE: (BINARY(4)) The code page derived from the coded character 
set identifier (CCSID) used for the data in the file or the extended attributes of the directory. 
If the returned value of this field is zero (0), there is more than one code page associated 
with the st_ccsid. If the st_ccsid is not a supported system CCSID, the st_codepage is set 
equal to the st_ccsid. 
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QPOL_ATTR_FILE_FORMAT: (CHAR(1)) The format of the stream file (*STMF). Valid 
values are: 


x'00' QPOL_FILE_FORMAT_TYPE1: The object has the same format as *STMF 
objects created on releases prior to Version 4 Release 4. It will be saved faster than 
a *TYPE2 *STMF to releases prior to Version 4 Release 4 of OS/400. It has a 
mimimum object size of 4096 bytes. 


x'01' QPOL_FILE_FORMAT_TYPE2: The object has high performance file access and 
is anew *STME object format in Version 4 Release 4 of OS/400. It will be saved 
slower than a *TYPE1 *STMF to releases prior to Version 4 Release 4 of OS/400. 
It has a minimum object size of 8192 bytes. 


QPOL_ATTR_UDFS_DEFAULT_FORMAT: (CHAR(1)) The default file format of stream 
files (*STMF) created in the user-defined file system. Valid values are: 


x'00' QPOL_UDFS_DEFAULT_TYPE1: The stream file (*STMF) has the same format 
as *STMFs created on releases prior to Version 4 Release 4 of OS/400. It will be 
saved faster than a *TYPE2 *STMF to releases prior to Version 4 Release 4 of 
OS/400. It has a mimimum object size of 4096 bytes. 


x'01l' QPOL_UDFS_DEFAULT_TYPE2: The object has high performance file access 
and is anew *STME object format in Version 4 Release 4 of OS/400. It will be 
saved slower than a *TYPE1 *STMF to releases prior to Version 4 Release 4 of 
OS/400. It has a minimum object size of 8192 bytes. 


QPOL_ATTR_JOURNAL_INFORMATION: Journaling information for this object. The 
journaling information format is defined in the QpOlstdi.h header file as data type 
QpOl_Journal_Info_t and is shown in the following table: 


QOp0l_Journal_Info_t 


[| Offset 
Cato an Hex |Type Field 


Current or last journal library name. If the value of the journaling status is 
QPOL_JOURNALED, then this field contains the name of the library containing the 
currently used journal. If the value of the journaling status is QPOL_NOT_JOURNALED, 
then this field contains the name of the library containing the last used journal. All bytes in 
this field will be set to binary zero if this object has never been journaled. 


Current or last journal name. If the value of the journaling status is QPOL_JOURNALED, 
then this field contains the name of the journal currently being used. If the value of the 
journaling status is QPOL_NOT_JOURNALED, then this field contains the name of the 
journal last used for this object. All bytes in this field will be set to binary zero if this object 
has never been journaled. 


Journal identifier (JID). This field associates the object being journaled with an identifier 
that can be used on various journaling-related commands and APIs. This field will be all 


26 


27 


28 


binary zeros for recorded byte-stream files. 


Journaling status. Current journaling status of the object. This field will be one of the 
following values: 


x'00' QPOL_NOT_JOURNALED: The object is currently not being journaled. 


x'0l' QPOL_JOURNALED: The object is currently being journaled. 


Last journaling start time. The number of seconds since the Epoch that corresponds to the 
last date and time for which the object had journaling started for it. This field will be set to 
binary zero if this object has never been journaled. 


Options. This field describes the current journaling options. This field is composed of 
several bit flags and contains one or more of the following bit values: 


x'08' QPOL_JOURNAL_SUBTREE: When this flag is returned, this object is a 
directory with IFS journaling subtree semantics. New objects created within this 
directory's subtree will inherit the journaling attributes and options from this 
directory. 


x'08' QPOL_JOURNAL_OPTIONAL_ENTRIES: When journaling is active, entries 
that are considered optional are journaled. The list of optional journal entries 
varies for each object type. See the Integrated file system topic for information 


regarding these optional entries for various objects. 


x'20' QPOL_JOURNAL_AFTER_IMAGES: When journaling is active, the image of the 
object after a change is journaled. 


x'40' QPOL_JOURNAL_BEFORE_IMAGES: When journaling is active, the image of 
the object prior to a change is journaled. 


QPOL_ATTR_ALWCKPWRT: (CHAR(1)) Whether a stream file (*STMF) can be shared 
with readers and writers during the save-while-active checkpoint processing. Valid values 
are: 


x'00' QPOL_NOT_ALWCKPWRT: The object can be shared with readers only. 
x'0l'’ QPOL_ALWCKPWRT: The object can be shared with readers and writers. 


QPOL_ATTR_CCSID: (BINARY(4)) The CCSID of the data and extended attributes of the 
object. 


QPOL_ATTR_SIGNED: (CHAR(1)) Whether an object has an OS/400 digital signature. 
This attribute is only returned for *STMF objects. Valid values are: 


x'00' QPOL_NOT_SIGNED: The object does not have an OS/400 digital signature. 
x'01' QPOL_SIGNED: The object does have an OS/400 digital signature. 


#29 QPOL_ATTR_SYS_SIGNED: (CHAR(1)) Whether the object was signed by a source that is 
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trusted by the system. This attribute is only returned for *STMF objects. Note: this attribute 
is not returned if the QPOL_ATTR_SIGNED attribute has the value QPOL_NOT_SIGNED. 
Valid values are: 


x'00' QPOL_SYSTEM_SIGNED_NO: (CHAR(1)) None of the signatures came from a 
source that is trusted by the system. 


x'0l' QPOL_SYSTEM_SIGNED_YES: The object was signed by a source that is 
trusted by the system. If the object has multiple signatures, at least one of the 
signatures came from a source that is trusted by the system. 


QPOL_ATTR_MULT_SIGS: (CHAR(1)) Whether an object has more than one OS/400 
digital signature. This attribute is only returned for *STMF objects. Note: this attribute is not 
returned if the QPOL_ATTR_SIGNED attribute has the value QPOL_NOT_SIGNED. Valid 
values are: 


x'00' QPOL_MULT_SIGS_NO: The object has only one digital signature. 


x'01' QPOL_MULT_SIGS_YES: The object has more than one digital signature. If the 
QPOL_ATTR_SYS_SIGNED attribute has the value QPOL_SYS_SIGNED, at 
least one of the signatures is from a source trusted by the system. 


QPOL_ATTR_DISK_STG_OPT (CHAR(1)) This option should be used to determine how 
auxiliary storage is allocated by the system for the specified object. This option can only be 
specified for stream files in the root (/), QOpenSys and user-defined file systems. This 
option will be ignored for *TYPE1 byte stream files. Valid values are: 


x'00' QPOL_STG_NORMAL: The auxiliary storage will be allocated normally. That is, 
as additional auxiliary storage is required, it will be allocated in logically sized 
extents to accomodate the current space requirement, and anticipated future 
requirements, while minimizing the number of disk I/O operations. 


x'01' QPOL_STG_MINIMIZE: The auxiliary storage will be allocated to minimize the 
space used by the object. That is, as additional auxiliary storage is required, it will 
be allocated in small sized extents to accomodate the current space requirement. 
Accessing an object composed of many small extents may increase the number of 
disk I/O operations for that object. 


x'02' QPOL_STG_DYNAMIC: The system will dynamically determine the optimum 
auxiliary storage allocation for the object, balancing space used versus disk I/O 
operations. For example, if a file has many small extents, yet is frequently being 
read and written, then future auxiliary storage allocations will be larger extents to 
minimize the number of disk I/O operations. Or, if a file is frequently truncated, 
then future auxiliary storage allocations will be small extents to minimize the 
space used. Additionally, information will be maintained on the stream file sizes 
for this system and its activity. This file size information will also be used to help 
determine the optimum auxiliary storage allocations for this object as it relates to 
the other objects sizes. 


32 QPOL_ATTR_MAIN_STG_OPT: (CHAR(1)) This option should be used to determine how 


main storage is allocated and used by the system for the specified object. This option can 
only be specified for stream files in the root (/), QOpenSys and user-defined file systems. 
Valid values are: 


x'00" 


x'Ol' 


x'02' 


QPOL_STG_NORMAL: The main storage will be allocated normally. That is, as 
much main storage as possible will be allocated and used. This minimizes the 
number of disk I/O operations since the information is cached in main storage. 


QPOL_STG_MINIMIZE: The main storage will be allocated to minimize the 
space used by the object. That is, as little main storage as possible will be allocated 
and used. This minimizes main storage usage while increasing the number of disk 
I/O operations since less information is cached in main storage. 


QPOL_STG_DYNAMIC: The system will dynamically determine the optimum 
main storage allocation for the object depending on other system activity and main 
storage contention. That is, when there is little main storage contention, as much 
storage as possible will be allocated and used to minimize the number of disk I/O 
operations. And when there is significant main storage contention, less main 
storage will be allocated and used to minimize the main storage contention. This 
option only has an effect when the storage pool's paging option is *CALC. When 
the storage pool's paging option is *FLXED, the behavior is the same as 
QPOL_STG_NORMAL. When the object is accessed thru a file server, this option 
has no effect. Instead, its behavior is the same as QPOL_STG_NORMAL. 


33 QPOL_ATTR_DIR_FORMAT: (CHAR(1)) The format of the specified directory object. 
Valid values are: 


x'00' 


x'Ol' 


QPOL_DIR_FORMAT_TYPE1: The directory of type *DIR has the original 
directory format. The Convert Directory (CVTDIR) command may be used to 
convert from the *TYPE1 format to the *TYPE2 format. 


QPOL_DIR_FORMAT_TYPE2: The directory of type *DIR is optimized for 
performance, size, and reliability compared to directories having the *TYPE1 
format. 


34 QPOL_ATTR_AUDIT: (CHAR(10)) The auditing value associated with the object. Valid 
values are: 


*NONE No auditing occurs for this object when it is read or changed regardless of 


the user who is accessing the object. 


*USRPRF — Audit this object only if the current user is being audited. The current user is 


tested to determine if auditing should be done for this object. The user 
profile can specify if only change access is audited or if both read and 
change accesses are audited for this object. 


*CHANGE Audit all change access to this object by all users on the system. 


*ALL 


Audit all access to this object by all users on the system. All access is 
defined as a read or change operation. 


300 =QPOL_ATTR_SUID: (CHAR(1)) Set effective user ID (UID) at execution time. This value 
is ignored if the specified object is a directory. Valid values are: 


x'00' QPOL_SUID_OFF: The user ID (UID) is not set at execution time. 


x'01' QPOL_SUID_ON: The object owner is the effective user ID (UID) at execution 
time. 


301 QPOL_ATTR_SGID: (CHAR(1)) Set effective group ID (GID) at execution time. Valid 
values are: 


x'00' QPOL_SGID_OFF: If the object is a file, the group ID (GID) is not set at 
execution time. If the object is a directory in the root (‘/'), QOpenSys, and 
user-defined file systems, the group ID (GID) of objects created in the directory is 
set to the effective GID of the thread creating the object. This value cannot be set 
for other file systems. 


x'01' QPOL_SGID_ON: If the object is a file, the group ID (GID) is set at execution 
time. If the object is a directory, the group ID (GID) of objects created in the 
directory is set to the GID of the parent directory.*& 


Number of requested attributes. The total number of requested attributes that Qp0IGetAttrQ 
returns. This field is required when the Attr_Array_ptr parameter is not NULL and must equal the 
number of constants in the array to which it points. When this field is zero, Qp0IGetAttr() returns all 
the attributes that are supported by the API and that are available for the object. 


Buffer_ptr 
(Input) A pointer to a buffer that the caller allocates for Qp01GetAttr( to return the requested data. 
The caller also sets the Buffer_Size_Provided parameter to the number of bytes that are allocated for 
this buffer. 


If the buffer provided is not large enough to hold all of the requested data, Qp0I1GetAttr() fills the 
buffer with as much data as possible and sets the value pointed to by the Buffer_Size_Needed_ptr 
parameter equal to the number of bytes required for all of the requested data to be returned. 


When the Buffer_ptr is NULL, Qp01GetAttr() returns the total number of bytes needed to hold all of 
the requested attributes and sets the Buffer_Size_Needed_ptr parameter to point to this value. 


Qp01GetAttr() identifies each entry that it returns in the buffer with the constant that the user 
supplied in the input structure pointed to by the Attr_Array_ptr parameter. Qp0I1GetAttr() returns this 
constant in the Attribute identification field. The constant must be used to identify the returned 
attribute because the attributes are returned in any order. 


Qp0lGetAttr() fills the buffer with an entry for each requested attribute in the following format: 


Buffer Pointer 


| Offset 
| Dec Hex |Type Field 


Attribute data. The attribute data that was requested. 


Attribute identification. The constant that identifies the returned attribute. Valid values follow and 
are the same constants as provided by the caller of Qp0IGetAttr(), pointed to by the Attr_Array_ptr 
parameter. 


See the Aftr_Array_ptr parameter for descriptions of each of these attribute values. 


0 QPOL_ATTR_OBJTYPE 
1 QPOL_ATTR_DATA_ SIZE 


2 QPOL_ATTR_ALLOC_SIZE 
QPOL_ATTR_EXTENDED_ATTR_SIZE 
QPOL_ATTR_CREATE_TIME 
QPOL_ATTR_ACCESS_TIME 
QPOL_ATTR_CHANGE_TIME 
QPOL_ATTR_MODIFY_TIME 
QPOL_ATTR_STG_FREE 
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QPOL_ATTR_CHECKED_OUT 
10 QPOL_ATTR_LOCAL_REMOTE 
11 QPOL_ATTR_AUTH 

12 QPOL_ATTR_FILE_ID 

13 QPOL_ATTR_ASP 

14 QPOL_ATTR_DATA_SIZE_64 


15 QPOL_ATTR_ALLOC_SIZE_64 
16 QPOL_ATTR_USAGE_ INFORMATION 
17 QPOL_ATTR_PC_READ_ONLY 


18 QPOL_ATTR_PC_HIDDEN 

19 QPOL_ATTR_PC_SYSTEM 

20 QPOL_ATTR_PC_ARCHIVE 

21 QPOL_ATTR_SYSTEM_ARCHIVE 

22 QPOL_ATTR_CODEPAGE 

23 QPOL_ATTR_FILE_FORMAT 

24 QPOL_ATTR_UDFS_DEFAULT_FORMAT 


25 QPOL_ATTR_JOURNAL_INFORMATION 
26 QPOL_ATTR_ALWCKPWRT 
27 QPOL_ATTR_CCSID 


28 QPOL_ATTR_SIGNED 
= 29 QPOL_ATTR_SYS_SIGNED 
30 QPOL_ATTR_MULT_SIGS 


31 QPOL_ATTR_DISK_STG_OPT 


32 QPOL_ATTR_MAIN_STG_OPT 


33 QPOL_ATTR_DIR_FORMAT 
34. QPOL_ATTR_AUDIT 

300  QPOL_ATTR_SUID 

301 QPOL_ATTR_SGID® 


Offset to next attribute entry. The offset to the next attribute entry in the buffer. This offset is 
relative to the start of the buffer. An offset of zero means that no more attribute entries follow. 


Reserved. A reserved field set to binary zero. 


Size of attribute data. The total size of all the data for this attribute. The special value of 0 in this 
field indicates that the attribute is not supported by the file system in which the object is stored. The 
attribute data is padded with hexadecimal zeros. The size indicated in this field does not include the 
padding bytes. 

Buffer_Size_Provided 
(Input) The number of bytes the caller allocates in a buffer for the return of requested data. The buffer 
is pointed to by the Buffer_ptr parameter. 


If this size is set to zero or is not large enough to hold all of the requested data, Qp0IGetAttr() fills 
the buffer with as much data as possible and sets the value pointed to by the Buffer_Size_Needed_ptr 
parameter equal to the number of bytes required for all of the requested data to be returned. 


Buffer_Size_Needed_ptr 


(Output) A pointer to the number of bytes that the caller needs to allocate for Qp0IGetAttr() to return 
all of the requested data. 


Num_Bytes_Returned_ptr 


(Output) A pointer to the actual number of bytes of data returned in the user buffer. This field is zero 
if the Buffer_ptr parameter is NULL. 


Follow_Symlnk 
(Input) If the last component in the Path_Name is a symbolic link, this parameter determines if the 
symbolic link or the path contained in the symbolic link is acted upon: Valid values are: 


0 QPOL_DONOT_FOLLOW_SYMLNK: A symbolic link in the last component is not followed. 
Attributes of the symbolic link object are returned. 


ZT QPOL_FOLLOW_SYMLNK: A symbolic link in the last component is followed. The attributes 
of the object contained in the symbolic link are returned. 


Authorities 


Note: Adopted authority is not used. 


[Authorization Required for Qp0lGetAttr() 
[Object Referredto  =——ss—i‘é;PS~~~~~~~——— Authority Required errno 
[Each directory, preceding the last component, in the Path.Name  [*X ————=S ACCESS 
(Object, when retrieving the QPOL_ATTR_AUTH attribute = == [‘OBJMGT —=—— [EACCES- 


Note: If the file system supports *ALLOBJ special authority and if you have *ALLOBJ special authority, 


you do not need the listed object authority. 


Return Value 


O Qp0lGetAttrQ was successful. 


-1 Qp0lGetAttrQ was not successful. The errno global variable is set to indicate the error. 


Error Conditions 


If Qp01GetAttr() is not successful, errno indicates one of the following errors: 
[EACCES] 


Permission denied. 
An attempt was made to access an object in a way forbidden by its object access permissions. 
The thread does not have access to the specified file, directory, component, or path. 


If you are accessing a remote file through the Network File System, update operations to file 
permissions at the server are not reflected at the client until updates to data that is stored locally by the 
Network File System take place. (Several options on the Add Mounted File System (ADDMFS) 
command determine the time between refresh operations of local data.) Access to a remote file may 


also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote 
systems. 


[EAGAIN] 


Operation would have caused the process to be suspended. 
[EBADFID] 

A file ID could not be assigned when linking an object to a directory. 

The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as possible. 
[EBADNAME] 


The object name specified is not correct. 


[EBUSY] 


Resource busy. 


An attempt was made to use a system resource that is not available at this time. 
[ECANCEL] 


Operation canceled. 


[ECONVERT] 


Conversion error. 


One or more characters could not be converted from the source CCSID to the target CCSID. 
[EDAMAGE] 


A damaged object was encountered. 


A referenced object is damaged. The object cannot be used. 
[EFAULT] 


The address used for an argument is not correct. 

In attempting to use an argument in a call, the system detected an address that is not valid. 

While attempting to access a parameter passed to this function, the system detected an address that is 
not valid. 


[EINTR] 


Interrupted function call. 


[EINVAL] 
The value specified for the argument is not correct. 
A function was passed incorrect argument values, or an operation was attempted on an object and the 
operation specified is not supported for that type of object. 
An argument value is not valid, out of range, or NULL. 
[EIO] 


Input/output error. 
A physical I/O error occurred. 


A referenced object may be damaged. 
[ELOOP] 
A loop exists in the symbolic links. 


This error is issued if the number of symbolic links encountered is more than POSIX_S YMLOOP 
(defined in the limits.h header file). Symbolic links are encountered during resolution of the directory 
or path name. 


[ENAMETOOLONG] 


A path name is too long. 


A path name is longer than PATH_MAX characters or some component of the name is longer than 
NAME_MAxX characters while _POSIX_NO_TRUNC is in effect. For symbolic links, the length of 
the name string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and 
NAME_MAxX values can be determined using the pathconf() function. 


[ENOENT] 
No such path or directory. 


The directory or a component of the path name specified does not exist. 


A named file or directory does not exist or is an empty string. 
[ENOMEM] 


Storage allocation request failed. 
A function needed to allocate storage, but no storage is available. 


There is not enough memory to perform the requested function. 
[ENOSPC] 
No space available. 
The requested operations required additional space on the device and there is no space left. This could 
also be caused by exceeding the user profile storage limit when creating or transferring ownership of 
an object. 
Insufficient space remains to hold the intended file, directory, or link. 
[ENOTAVAIL] 
Independent auxiliary storage pool (ASP) is not available. 
The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage (RCLSTG) 
processing. 
To recover from this error, wait until processing has completed for the independent ASP. 
[ENOTDIR] 
Not a directory. 
A component of the specified path name existed, but it was not a directory when a directory was 
expected. 
Some component of the path name is not a directory, or is an empty string. 
[ENOTSAFE] 


Function is not allowed in a job that is running with multiple threads. 


[ENOTSUP] 
Operation not supported. 
The operation, though supported in general, is not supported for the requested object or the requested 
arguments. 

[EOFFLINE] 
Object is suspended. 
You have attempted to use an object that has had its data saved and the storage associated with it 
freed. An attempt to retrieve the object's data failed. The object's data cannot be used until it is 


successfully restored. The object's data was saved and freed either by saving the object with the 
STG(*FREE) parameter, or by calling an API. 


[EOVERFLOW] 


Object is too large to process. 


The object's data size exceeds the limit allowed by this function. 
[EPERM] 


Operation not permitted. 


You must have appropriate privileges or be the owner of the object or other resource to do the 
requested operation. 


[EROOBJ] 
Object is read only. 


You have attempted to update an object that can be read only. 
[EUNKNOWN] 


Unknown system state. 


The operation failed because of an unknown system state. See any messages in the job log and correct 
any errors that are indicated, then retry the operation. 


If interaction with a file server is required to access the object, errno could also indicate one of the following 
errors: 


[EADDRNOTAVAIL] 


Address not available. 


[ECONNABORTED] 


Connection ended abnormally. 


[ECONNREFUSED] 


The destination socket refused an attempted connect operation. 


[ECONNRESET] 


A connection with a remote socket was reset by that socket. 


[EHOSTDOWN] 


A remote host is not available. 


[EHOSTUNREACH] 


A route to the remote host is not available. 


[ENETDOWN] 


The network is not currently available. 


[ENETRESET] 


A socket is connected to a host that is no longer available. 


[ENETUNREACH ] 


Cannot reach the destination network. 


[ESTALE] 


File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may have been deleted at 
the server. 


[ETIMEDOUT] 


A remote host did not respond within the timeout period. 


[EUNATCH] 
The protocol required to support the specified address family is not available at this time. 


Error Messages 


The following messages may be sent from this function: 
Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPFAOD4 E File system error occurred. Error number &1 
CPF3CF2 E Error(s) occurred during running of &1 API. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 


1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 
oO Where multiple threads exist in the job. 


oO The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


m Root 

m QOpenSys 

m User-defined 

mw QNTC 

mw QSYS.LIB 

m “Independent ASP QSYS.LIB 
mw QOPT 


2. QSYS.LIB #and Independent ASP QSYS.LIB *&File System Differences 


Qp0IGetAttr() could return zero for the QPOL_ATTR_ACCESS_TIME value (in the buffer area) 
under some conditions. 


cs 
Refer to the CL ecpianning ee book for more information regarding which object types maintain 


usage information that is returned for the QPOL_ATTR_USAGE_INFORMATION attribute. 


When Qp01GetAttr() is performed on a physical file member, the 
QPOL_ATTR_JOURNAL_INFORMATION attribute will contain journaling information applicable 
to the physical file that contains the member. 


Related Information 


e The <QpOlstdi.h> file (see Header Files for UNIX-Type Functions) 


e The <qlg.h> file (see Header Files for UNIX-Type Functions) 

e *chmod()--Change File Authorizations * 

e fstat()--Get File Information by Descriptor 

e |stat()--Get File or Link Information 

e QlgGetAttrQ--Get Attributes (using NLS-enabled path name) 

e QlgStatQ--Get File Information (using NLS-enabled path name) 

e QlgLstat()--Get File or Link Information (using NLS-enabled path name) 
e Qp0lSetAttr()--Set Attributes*® 


e stat()--Get File Information 


Example 


Following is an example showing a call to Qp0IGetAttr(). The example also shows a call to 
QpolSaveStgFree(). 


See Code disclaimer information for information pertaining to code examples. 


[BORK KR KK KK KR KK KK  / 


#include "QpOlstdi.h" 
#include <stdio.h> 
#include <errno.h> 
#include <stdlib.h> 
#include <sys/types.h> 
#include <qusec.h> 
#include <time.h> 


int Save(Qp01l_Pathnames_t *Path_name_ptr) 
{ 


[BOR KK KK KK KK RK RK OK KK KKK / 


/* No function here in the example */ 
[BORK KKK KKK KR RK RK KK KK / 


}; 


void SaveAnObject (Qp01_Pathnames_t *Path_name_ptr, 


int *Return_code_ptr, 
int *Return_value_ptr, 
void *Function_Ct1Blk_ptr) 


[BORK KK KR KKK RK RR KK KK KK / 


/* This function saves a file and its hard links to tape. ard 

[BORK KR KK KKK KK KR KK KK KK KK KK / 

int rc? 

if ((Path_name_ptr == (Qp01_Pathnames_t *) NULL) | | 
(Path_name_ptr->Number_Of_Names == 0)) 


{ 
printf("In User Exit Program with null Path \n"); 


} 


else 


{ 


/* This example calls a function (Save) that could call the */ 


/* Save Object (QsrSave) API. The QsrSave API is designed to */ 
/* save a copy of one or more objects that can be used in the */ 


/* integrated file system. For details on using QsrSave, see 
/* the Backup and Recovery API part. 


re = (Save(Path_name_ptr)); 
*Return_code_ptr = rc; 
*Return_value_ptr = errno; 
if (re == 0) 


/* Other processing for a successfully saved object. */ 


else 
{ 
/* Optional processing such as storing information AY. 
/* to be returned to the caller in the function */ 
/* control block area, or building a list of the aad 
/* files whose save attempts failed, or other. ae 
} 
} 
return, 
} /* end SaveAnObject exit program */ 


int main (int argc, char *argv[]) 
{ 
#define MYPN "ADIR/ASTMF" 


const char US_const[3]= "US"; 
const char Language_const [4]="ENU",; 
const char Path _Name_Del_const[2] = "/"; 


struct pnstruct 


{ 
Qlg_Path_Name_T qlg_struct; 
char pn[1]; 


}; 
struct pnstruct pns; 
struct pnstruct *pns_ptr = NULL; 


struct attrStruct 

{ 
QpOl_AttrTypes_List_t attr_struct; 
uint AttrTypes[10]; 

}; 

struct attrStruct Attr_types_ptr; 

QpOl_Attr_Header_t *attrPtr; 

char *attrValp; 


Qp0l_StgFree_Function_t User_function; 


struct 
{ 
uint AnyData_to_the_exitprogram; 
uint AnyData_not_processed_by_the_API; 


} CtlBlkAreaName; 


time_t mytime; 

char BufferArea[250]; 

unsigned int buff_size_provided; 
unsigned int buff_size_needed = 0; 
unsigned int num_bytes_returned = 
unsigned int follow_sym; 

int done=0; 

int. rc 

int returned_data_index = 0; 


0; 


[BORK KK KR KK KK KK RK RR KK KK OK KK KKK / 


/* Initialize Get Attributes Parameters *], 
[BORK KKK KK KK RR RK KK KK / 
memset ((void*)&pns, 0x00, sizeof(struct pnstruct)); 
pns.glg_struct.CCSID = 37; 

memcpy (pns.qlg_struct.Country_ID,US_const, 2); 

memcpy (pns.qlg_struct.Language_ID, Language_const, 3) ; 
pns.gqlg_struct.Path_Type = 0; 

pns.gqlg_struct.Path_Length = sizeof (MYPN)-1; 

memcpy (pns.qlg_struct.Path_Name_Delimiter, Path_Name_Del_const,1)j; 
memcpy (pns.pn,MYPN, sizeof (MYPN) ); 

memset ((void *) &Attr_types_ptr, 0x00,sizeof(struct attrStruct)); 
pns_ptr = &pns; 


Attr_types_ptr.attr_struct.Number_Of_RegAttrs = 2; 
Attr_types_ptr.AttrTypes[0] = QPOL_ATTR_ACCESS_TIME; 
Attr_types_ptr.AttrTypes[1] = QPOL_ATTR_STG_FREE; 
buff_size_provided = 250; 

follow_sym = QPOL_FOLLOW_SYMLNK; 


[BOR KK KKK KK KK RR KK KK KK / 


/* Call the Qp01GetAttr() API to retrieve attributes to */ 
/* determine if selection criteria can be met for calling */ 
/* the QpO0lSaveStgFree() API. */ 


[BORK KKK KKK KK RR RK KK KK / 


re = Qp0lGetAttr((Qlg_Path_Name_T *)é&pns, 
(Qp01_AttrTypes_List_t *) &Attr_types_ptr, 
BufferArea, 
buff_size_provided, 
&buff_size_ needed, 
énum_bytes_returned, 
follow_sym) ; 
if (re == 0) /* check API return code */ 
{ 
/* Must first check if any data was returned. */ 
if (num_bytes_returned > 0) 
{ 
attrPtr = (Qp01l_Attr_Header_t *)BufferArea; 
while (!done) 
{ 
attrValp = (char *)attrPtr + 
sizeof (Qp0l_Attr_Header_t); /* Point to attr value * / 
ee ee ee ee 


/* The following code prints the two attributes that */ 


/* were returned. Add more code here, for example, Ay 
/* to determine if the returned attributes meet ay 
/* the criteria or policies for storage freeing. 7] 
[®ORK KKK KR KK KK KK KK OK RK KK ee / 
printf (TT a I I A I I I A A I I I I TH) . 
printf ("Attr ID #%d = %d - ", 


returned_data_index, 
attrPtr->Attr_ID); 
if (attrPtr->Attr_Size > 0) 
{ 
switch (attrPtr->Attr_ID) 
{ 
case QPOL_ATTR_ACCESS_TIME: 
printf ("QPOL_ATTR_ACCESS_TIME\n") ; 
memcpy ((void *) &mytime, 
(void *)attrValp, 
attrPtr->Attr_Size); 
printf ("Ss", ctime (&mytime) ); 
break; 
case QPOL ATTR_STG_FREE: 
printf ("QPOL_ATTR_STG_FREE\n"); 
switch (attrValp[0]) 
{ 
case QPOL_SYS_STG_FREE: 
printf ("--Is storage freed--\n"); 


break; 

case QPOL_SYS_NOT_STG_FREE: 
printf ("--Is not storage freed--\n"); 
break; 

default: 


printf ("Invalid data: %d.\n", 
attrValp[0]); 


break; 
} 
break; 
default: 
printf ("Undefined return type (attr id unknown.) \n"); 
break; 


} /* end switch * / 


} 
else 
printf("Attribute has no value\n"); 

printf ("***Size of this attr's data: %d\n", 
attrPtr->Attr_Size); 

printf ("***Offset to next attr: %d\n", 
attrPtr->Next_Attr_Offset); 

++returned_data_index; 


if (attrPtr—->Next_Attr_Offset > 0) /* If more data */ 
attrPtr = (Qp0l_Attr_Header_t *) /* Set attribute ef 

& (BufferArea[attrPtr->Next_Attr_Offset]); /* pointer */ 
else /* No more data */ 
done = 1; /* End the loop Lad 


} 


[ORK KKK KKK RK KK KK KK KKK KK KKK KK / 


/* Initialize Save Storage Free Parameters. The path Berd 
/* name parameter was already initialized as part of the */ 
/* call to Qp0l1GetAttr() API and is assumed, in this * / 
/* example, to be the same pathname. Both APIs require ara 
/* the same path name format. & ff 


[BORK KKK KKK KK KK KR A KK KK A / 


memset ((void *) &User_function, 0x00, sizeof (Qp01_StgFree_Function_t)); 


User_function.Mltthdacn[0] = QPOL_MLTTHDACN_NOMSG; 
User_function.Function_Type = QPOL_USER_FUNCTION_PTR; 
User_function.Procedure = &SaveAnObject; 


re = Qp0lSaveStgFree((Qlg_Path_Name_T *)é&pns, 
&User_function, 
&CtlBlkAreaName) ; 

if(rc == 0) 

printf ("Qp01SaveStgFree() Successful!"); 

else 

{/* Unsuccessful return from Qp0lSaveStgFree() API. */ 

/* The following code prints the errno value message. */ 


re = errno; 
printf ("ERROR on Qp0lSaveStgFree(): error = %d\n", rc); 
perror ("Error message"); 
} 
} /* if (num_bytes_returned > 0) */ 
else 
rc = EUNKNOWN; 
} /* end rcGA == 0, Qp0lGetAttr() was successful */ 
else 
{ 
re = errno; 
printf ("ERROR on Qp0l1GetAttr(): error = %d\n", rc); 


perror ("Error message"); 


} 
return (rc); 
} /* end main */ 


API introduced: V4R3 


Top | UNIX-Type APIs | APIs by category 


Qp0IGetPathFromFilelD()--Get Path Name of 
Object from Its File ID 


Syntax 


#include <Qp0lstdi.h> 


char *Qp01GetPathFromFileID(char *buf, size_t size, 
QpOlFID_t fileid); 


Threadsafe: Yes 


The Qp0IGetPathFromFileID(Q function determines an absolute path name of the file identified by fileid 
and stores it in buf. The components of the returned path name are not symbolic links. If the file has more 
than one path name, only one is returned. 


The access time of each directory in the absolute path name of the file (excluding the file itself) is updated. 
If buf is a NULL pointer, Qp0IGetPathFromFileIDQ) returns a NULL pointer and the EINVAL error. 
The contents of buf after an error are not defined. 


Qp01GetPathFromFileIDQ) is supported in the root (/), QOpenSys, and user-defined file systems. 


Parameters 


buf 


(Output) A pointer to a buffer that will be used to hold an absolute path name of the file identified 
by fileid. The buffer must be large enough to contain the full path name including the terminating 
NULL character. 


The path name is returned in the CCSID (coded character set identifier) currently in effect for the 
job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default 
CCSID of the job. 


See QlgGetPathFromFileIDQ--Get Path Name of Object from Its File ID (using NLS-enabled path 
name) for a description and an example of supplying the buf'in any CCSID. 


size 
(Input) The number of bytes in the buffer buf. 


fileid 


(Input) The identifier of the file whose path name is to be returned. This identifier is logged in audit 
journal entries to identify the file being audited. See the Parent File ID and Object File ID fields of 


a 
the audit journal entries described in the iSeries Security Reference e book. 


Authorities 


Note: Adopted authority is not used. 
Authorization required for Qp0IGetPathFromFileIDQ) 


[Object Referred to [Authority Required [errno 
[Each directory in the path name preceding the file | *RX [EACCES 
[The file itself | *R |EACCES 


Return Value 


value 
Qp0I1GetPathFromFileIDQ was successful. The value returned is a pointer to buf. 
NULL 


Qp01GetPathFromFileIDQ was not successful. The errno global variable is set to indicate the 
error. After an error, the contents of buf are not defined. 


Error Conditions 


If Qp01GetPathFromFileIDQ is not successful, errno usually indicates one of the following errors. Under 
some conditions, errno could indicate an error other than those listed here. 


[EACCES] 
Permission denied. 
An attempt was made to access an object in a way forbidden by its object access permissions. 
The thread does not have access to the specified file, directory, component, or path. 
If you are accessing a remote file through the Network File System, update operations to file 
permissions at the server are not reflected at the client until updates to data that is stored locally by 
the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) 
command determine the time between refresh operations of local data.) Access to a remote file may 


also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote 
systems. 


[EAGAIN] 


Operation would have caused the process to be suspended. 
[EBADFID] 

A file ID could not be assigned when linking an object to a directory. 

The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as possible. 


[EBUSY] 


Resource busy. 


An attempt was made to use a system resource that is not available at this time. 


[EDAMAGE] 


A damaged object was encountered. 


A referenced object is damaged. The object cannot be used. 


[EFAULT] 


The address used for an argument is not correct. 
In attempting to use an argument in a call, the system detected an address that is not valid. 
While attempting to access a parameter passed to this function, the system detected an address that 


is not valid. 


[EFILECVT] 


File ID conversion of a directory failed. 


Try to run the Reclaim Storage (RCLSTG) command to recover from this error. 


[EINVAL] 


The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on an object and 
the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. 


[EIO] 


Input/output error. 
A physical I/O error occurred. 


A referenced object may be damaged. 


[ENOENT] 
No such path or directory. 


The directory or a component of the path name specified does not exist. 
A named file or directory does not exist or is an empty string. 


No path names were found for this fileid or the user is not authorized to any of the paths. 


[ENOMEM] 


Storage allocation request failed. 
A function needed to allocate storage, but no storage is available. 


There is not enough memory to perform the requested function. 


[ENOTAVAIL] 
Independent Auxiliary Storage Pool (ASP) is not available. 


The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage (RCLSTG) 
processing. 


To recover from this error, wait until processing has completed for the independent ASP. 


[ERANGE] 


A range error occurred. 
The value of an argument is too small, or a result too large. 


The size argument is too small. It is greater than zero but smaller than the length of the path name 
plus a NULL character. 


[ESTALE] 


File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may have been deleted 
at the server. 


[EUNKNOWN] 
Unknown system state. 


The operation failed because of an unknown system state. See any messages in the job log and 
correct any errors that are indicated, then retry the operation. 


Error Messages 


The following messages may be sent from this function: 


CPE3418 E Possible APAR condition or hardware failure. 

CPFAOD4E _ File system error occurred. Error number &1. 

CPF3CF2 E Error(s) occurred during running of &1 API. 

CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 


1. File System Differences 


The following file systems do not support Qp0IGetPathFromFileID(Q): 


o Network File System 

o QSYS.LIB 

oO #Independent ASP QSYS.LIB 
o QDLS 

Oo QOPT 

Oo QFileSvr.400 

Oo QNetWare 

Oo QNTC 


Related Information 


e The <Qp0lstdi.h> file (see Header Files for UNIX-Type Functions) 


e QleGetPathFromFile[IDQ--Get Path Name of Object from Its File ID (using NLS-enabled path 
name) 


Example 


The following example determines the path name of a file, given its file ID. In this example, the fileid is 
hardcoded. More realistically, the fileid is obtained from the audit journal entry and passed to 
Qp01GetPathFromFileIDQ. 


#include <Qp0lstdi.h> 
#include <stdio.h> 


main () 
{ 
char path[1024],; 
QpOlFID_t fileid = {0x00, 0x00, 0x00, Ox00, Ox00, Ox00, 0x00, Ox00, 
0x00, 0x00, 0x00, Ox00, Ox80, OxFF, OxCF, 0x00}; 


if (Qp01GetPathFromFileID(path, sizeof(path), fileid) == NULL) 
perror ("Qp01GetPathFromFileID() error"); 
else 
printf("The file's path is: %s\n", path); 
} 


Output: 


The file's path is: /myfile 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


Qp0IlOpen()--Open File 


Syntax 


#include <Qp0lstdi.h> 


int Qp0lOpen(Qlg_Path_Name_T *Path_Name, 
int oflag, .. .); 


Theadsafe: Conditional; see Usage Notes on open() API. 


The Qp0lOpen() function, similar to the open() function, opens a file and returns a number called a file 
descriptor. Qp0lOpen(differs from open() in that the Path_Name parameter is a pointer to a 
Qlg_ Path_Name_T structure instead of a pointer to a character string. 


Only the Path_Name parameter is described here. For a discussion of the other parameters, authorities 
required, return values, and related information, see open()--Open File. 


Note: To use this API with large file APIs, you must specify the O_LLARGEFILE flag on the oflag 
parameter. 


Parameters 


Path_Name 


(Input) The path name of the file to be opened. This path name is in the Qlg_Path_Name_T format. 
For more information on this structure, see Path Name Format. 


Related Information 


e The <fentl.h> file (see Header Files for UNIX-Type Functions) 
@ open()--Open File 


e close()--Close File or Socket Descriptor 


Example 


The following example creates and opens an output file for exclusive access. This program was stored in a 
source file with CCSID 37, so the constant string "newfile" will be compiled in coded character set 
identifier (CCSID) 37. Therefore, the country or region and language specified are United States English, 
and the CCSID specified is 37. 


#include <fcntl.h> 
#include <stdio.h> 
#include <Qp0lstdi.h> 


main () 


{ 
int fildes; 


const char US_const[3]= "US"; 
const char Language_const [4]="ENU",; 
const char Path_Name_Del_const[2] = "/"; 


struct pnstruct 
{ 
Qlg_Path_Name_T gqlg_struct; 
char pn[7]; 
}; 
struct pnstruct pns; 
struct pnstruct *pns_ptr = NULL; 


char fn[]="newfile"; 


memset ((void*)&pns, 0x00, sizeof(struct pnstruct)); 
pns.qlg_struct.CCSID = 37; 

memcpy (pns.qlg_struct.Country_ID,US_const, 2); 

memcpy (pns.qlg_struct.Language_ID, Language_const,3);; 
pns.qlg_struct.Path_Type = 0; 
pns.qlg_struct.Path_Length = sizeof(fn) - 1; 

memcpy (pns.qlg_struct.Path_Name_Delimiter, 
Path_Name_Del_const,1); 

memcpy (pns.pn, fn, sizeof (fn)); 


pns_ptr = &pns; 
if (fildes = Qp010pen((Qlg_Path_Name_T *)pns_ptr, 
O_WRONLY|O_CREAT|O_EXCL, S_IRWXU)) == -1) 


{ 


perror ("Qp010pen() error"); 


} 


API introduced: V4R4 


Top | UNIX-Type APIs | APIs by category 


Qp0!IProcessSubtree()--Process a Path Name 


Syntax 


#include <Qp0lstdi.h> 


int Qp0OlProcessSubtree ( 

Qlg_Path_Name_T *Path_Name, 

uint Subtree_level, 
Qp0l_Objtypes_List_t *Objtypes_array_ptr, 

uint Local_remote_obj, 
Qp0l_IN_EXclusion_List_t *IN_EXclusion_ptr, 

uint Err_recovery_action, 
Qp0l_User_Function_t *UserFunction_ptr, 

void *Function_CtliBlk_ptr, ...); 


Service Program Name: QPOLLIB2 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The Qp0IProcessSubtree() function searches the directory tree under a specific path name. It selects and 
passes objects, one at a time, to an exit program that is identified on its call. The exit program can be either 
a procedure or a program. 


Qp0IProcessSubtree() performs recursive read operations to access any object in any file system. The 
order in which objects are selected and passed to the exit program can vary within a given file system and 
within a given directory, dependent on file system rules. The only guaranteed ordering is that all selected 
objects within a given directory are passed to the exit program before the parent directory is passed to the 
exit program. 


Parameters 


Path_Name 


(Input) The path name where Qp0IProcessSubtree() starts its search. All relative path names are 
relative to the current directory at the time of the call to Qp0IProcessSubtree(). This path name is 
in the Qlg Path _Name_T format. For more information on this structure, see Path Name Format. 


The Path_Name parameter must be NULL to use the IN_EXclusion_ptr parameter to enter multiple 
path names for inclusion on a single call to Qp0IProcessSubtree(). 


Subtree_level 


(Input) An unsigned integer that tells Qp0IProcessSubtree() whether or not to open subdirectories 
in the path being processed. Valid values follow: 


0 


QPOL_SUBTREE_YES: All subdirectories are opened by Qp0IProcessSubtree() so that 
the objects they contain are sent to the exit program if they meet the caller's selection 


criteria. 


QPOL_SUBTREE_NO: Only first-level objects are processed. The names of 
subdirectories, which meet the selection criteria, are passed to the exit program, but they 
are not opened by Qp0IProcessSubtree(). Thus, the objects the subdirectories contain are 
not matched against selection criteria and therefore are not sent to the exit program. 


Objtypes_array_ptr 


(Input) A pointer to an array of object types. Each entry in the array identifies an object type that 
Qp0IProcessSubtree() 2 uses to determine what will be passed to the exit program. The 
Number of object types field contains the total number of object types in the array. A NULL 
pointer means that there is no filtering according to object type and that all object types that meet 
other selection criteria are passed to the exit program. 


The structure for this parameter follows. 


Object Types ArrayPointer 


[Offset 
= Hex Type Field 


| BINARY(4) Number of object types 


4 4 ARRAY (*) of {Array of object types structure 
CHAR(11) 


Array of object types structure 


An array identifying each object type 2* used to determine what will be passed to the exit 
program when processing a path. Each entry is limited to 11 characters, including a 
NULL terminator, and is padded with blanks. Object types must be entered in standard 
OS/400 object type format which is all capital letters, preceded by an asterisk (*). For a 
complete list of the available object types, see Object Types in the CL topic. 


Qp0IProcessSubtree() verifies that valid OS/400 object types are entered and returns the 
errno EINVAL when an object type that is not valid is entered. Although some object types 
are scoped to a specific file system, Qp01ProcessSubtree() does not validate object types 
according to file systems. 


Valid special values for this parameter follow: 


*ALLDIR: 


Select all directory object types. This includes *LIB, *DIR, *FLR, *FILE, and 
*DDIR object types. 
2**A LLOSYS: 


Select all QSYS.LIB object types. This includes all objects in the QSYS.LIB file 
system and all independent ASP QSYS.LIB file systems which are available when 
the API is first called. 


Note: IN_EXclusion_ptr must also be specified as an inclusion array. If *NOQSYS 
is specified, *ALLQSYS cannot also be specified.*& 


*“ALLSTMP: 


Select all OS/400 stream file object types. This includes *MBR, *DOC, *STMF, 
*DSTMEF, and *USRSPC object types. 

*“MBR: 
Select all OS/400 database file member types. 


2"NOOSYS: 


Exclude all QSYS.LIB object types. This includes all objects in the QSYS.LIB file 
system and all independent ASP QSYS.LIB file systems which are available when 
the API is first called. 


Note: This special value only has meaning if '/ or '/asp_name' is specified for the 
Path_Name parameter (where asp_name is the name of an independent ASP which 
is available when the API is first called). Additionally, if IN_EXclusion_ptr is 
specified, it must only be as an exclusion array. If *ALLQSYS is specified, 
*NOQSYS cannot also be specified.“ 


Number of object types 


The number of types included in the search. 


Local_remote_obj 


(Input) An unsigned integer that tells Qp0IProcessSubtree() whether to select only local objects, 
only remote objects, or both. Note that the decision of whether a file is local or remote varies 
according to the respective file system rules. Objects in file systems that do not carry either a local 
or remote indicator are treated as remote. Valid values follow: 


0 
QPOL_LOCAL_REMOTE_OBJ: Both local and remote objects are passed to the exit 
program. 

1 
QPOL_LOCAL_OBJ: Only local objects are passed to the exit program. 

2 


QPOL_REMOTE_OBJ: Only remote objects are passed to the exit program. 


IN_EXclusion_ptr 


(Input) A pointer to an array of pointers. Each pointer in the array points to a specific path name 
that identifies a directory, and all of its subdirectories, that Qp01ProcessSubtree() cither includes 
or excludes in its search to find objects that meet the caller's input criteria. If this pointer is not 
NULL, the IN_EXclusion pointer type must indicate whether the list is an inclusive or exclusive 
list. The Number of pointers field must contain the number of path names for inclusion or exclusion 
on the search. 


Use an inclusive list to specify multiple path names for searches on a single call to 
Qp0IProcessSubtree() versus using the Path_Name parameter, which searches only one path per 
call. The Path_Name parameter and an inclusive list are mutually exclusive. EINVAL is returned if 
both parameters are specified. The IN_EXclusion_ptr must be NULL if not used. All of the rules 
that apply to a single Path_Name entry apply to each inclusive list entry. 


While an inclusion list allows the caller of Qp0IProcessSubtree() to identify multiple path names 


for processing, Qp0IProcessSubtree() does not perform any verification to ensure uniqueness of 
path names or to verify any other relationship between path names entered in the inclusion array. 
For example, if the path names entered represent nested directories, Qp0IProcessSubtree() calls 
the exit program multiple times without any error message or other notification of this nesting. 


Specify the root directory for a given file system as an exclusive list entry to eliminate that file 
system from a search. 


All relative path names are relative to the current directory of the job that calls 
Qp01ProcessSubtree(). 


The structure for this parameter follows. 


IN_EXclusion Pointer. 


This points to a list of path names to either include or exclude from a search. 


| Offset 
[Dec Hex Type Field 


IN_EXclusion pointer type 


Whether a path name array contains directories that are included or contains directories that 
are excluded. Valid values follow: 


0 
QPOL_INCLUSION_TYPE: An inclusion array is identified. 


QPOL_EXCLUSION_TYPE: An exclusion array is identified. 
Number of pointers 
The number of path name pointers that are in the inclusion or exclusion array. 
Path name pointers 


An array of pointers. Each pointer points to a path name that is included or excluded. Each 
path name must follow the Qlg_Path_Name_T structure. For more information on this 
structure, see Path Name Format. 


Reserved 


A reserved field. This field must be set to binary zero. 


Err_recovery_action 


(Input) An unsigned integer that describes how Qp0IProcessSubtree() handles errors that are not 
severe enough to force the API to end processing. Valid values follow: 


0 
QPOL_PASS_WITH_ERRORID: Calls the exit program and specifies the name (when 


the name is available) of the object being accessed when an error occurs. This value also 
sends a valid errno to the exit program. 


QPOL_BYPASS_NO_ERRORID: Bypasses the object being accessed when an error 
occurs, and moves to process the next object in the tree without notification to the calling 
program or to the exit program that an error has occurred. 


QPOL_JOBLOG_NO_ERRORID: Sends message CPDA1CO0 to the job log to identify 
the object being accessed when an error occurs. This value returns to process the next 
object without notification to the calling program or to the exit program that an error has 
occurred. 


QPOL_NULLNAME_ERRORID: Calls the exit program with a NULL object name and 
a valid errno. 


QPOL_END_PROCESS_SUBTREE: Quits Qp0IProcessSubtree() when an error occurs, 
and returns to the calling program, regardless of the error type. Note that the exit program 
is still given a call but cannot override the caller's decision to end processing. Calling the 
exit program allows the exit program to perform other tasks before the API returns to the 
caller. For example, the exit program can put information in the function control block that 
can be processed by the caller when the caller regains control. 


UserFunction_ptr 
(Input) A pointer to the name of an exit program that the caller wants Qp0IProcessSubtree() to call 
upon finding an object that matches the selection criteria. This exit program can be either a 
procedure or a program. See #* Process a Path Name Exit Program *& for the syntax of the user exit 
program. 


The structure for this parameter follows. 


User Function Pointer. 


This points to the user exit program. The exit program can be a procedure or a program. 


| Offset 
_— Hex Type Field 


| BINARY(4) Function type flag 

| 4 4 CHAR(10) Program library 

| 14 E CHAR(10) Program name 

| 24 18 |CHAR(1) Multithreaded job action 

| 25 19 |CHAR(7) Reserved 

| 32 20 ~~‘ |PP(*) Procedure pointer to the exit procedure 


Function type flag 


An unsigned integer that indicates whether the user-supplied exit program that is called by 


Qp0IProcessSubtree() is a procedure or a program. Valid values follow: 


0 


QPOL_USER_FUNCTION_PTR: A user procedure is called. 


QPOL_USER_FUNCTION_PGM: A user program is called. 


Multithreaded job action 


(Input) A CHAR(1) value that indicates the action to take in a multithreaded job. The 
default value is QPOL_MLTTHDACN_SYSVAL. For release compatibility and for 
processing this parameter against the QMLTTHDACN system value, x'00, x'01', x'02', & 
x'03' are treated as x'FO'" x'F1', x'F2', and x'F3'. Valid values follow: 


x'00' 


x01’ 


x'02' 


x'03' 


QPOL_MLTTHDACN_SYSVAL: The API evaluates the QMLTTHDACN system 
value to determine the action to take in a multithreaded job. Although the API can 
make repetitive calls to an exit program, the system value is evaluated once before 
Qp0IProcessSubtree() issues its first exit program call. This value is used on 
subsequent calls until the API returns control to its caller. Valid QMLTTHDACN 
system values follow: 


'l Uy 
Call the exit program. Do not send an informational message. 

) Uy 
Call the exit program. Send informational message CPI3C80. 
QpO0IProcessSubtree() may call the exit program multiple times; however, 
this message is sent only once for each call to Qp01ProcessSubtree(). 

'3 Uy 


The exit program is not called when the API determines that it is running 
in a multithreaded job. ENOTSAFE is returned. 


QPOL_MLTTHDACN_NOMSG: Call the exit program. Do not send an 
informational message. 


QPOL_MLTTHDACN_MSG: Call the exit program. Send informational message 
CPI3C80. Qp01ProcessSubtree() may call the exit program multiple times; 
however, this message is sent only once for each call to Qp0IProcessSubtree(). 


QPOL_MLTTHDACN_NO: The exit program is not called when the API 
determines that it is running in a multithreaded job. ENOTSAFE is returned. 


Procedure pointer to the exit procedure 


A procedure pointer to the procedure that Qp0IProcessSubtree() calls. This field must be 
NULL if a program is called instead of a procedure. 


Program library 


The library in which the called program, identified by Program name, is located. This field 
must be blank if a procedure is called instead of a program. 


Program name 


The name of the program that is called. The program is located in the library identified by 
Program library. This field must be blank if a procedure is called instead of a program. 


Reserved 


A reserved field. This field must be set to binary zero. 


Function_CtlBlk_ptr 


(Input) A pointer that Qp0IProcessSubtree() passes to the user-defined exit program that is called. 
Qp0IProcessSubtree() does not process this pointer or what is referred to by the pointer. It passes 
the pointer as a parameter to the user-defined exit program that was specified. This is a means for 
the caller of Qp01ProcessSubtree() to pass information to and from the Process a Path Name exit 
program. 


Authorities 


Note: Adopted authority is not used. 


Authorization Required for 


Qp01ProcessSubtree() 
Object Referred to Authority Required errno 
Each directory, preceding the last component, in a Path Name *X EACCES 
The Path Name directory and all subdirectories of the Path Name *RX EACCES 
that are included in the search. 
Each directory, preceding the last component, in any path name *X EACCES 
pointed to by the IN_EXclusion ptr 
The Path Name directory and all subdirectories of any path name *RX EACCES 
pointed to by an inclusive list 
Any called program pointed to by the UserFunction_ptr parameter *X EACCES 
Any library that contains the called program pointed to by the *X EACCES 


UserFunction_ptr parameter 


Return Value 


0 
Qp01ProcessSubtree() was successful. 
-] 


Qp01ProcessSubtree() was not successful. The errno variable is set to indicate the error. 


Error Conditions 


If Qp01IProcessSubtree() is not successful, the errno indicates one of the following errors: 
[EACCES] 


Permission denied. 
An attempt was made to access an object in a way forbidden by its object access permissions. 
The thread does not have access to the specified file, directory, component, or path. 


If you are accessing a remote file through the Network File System, update operations to file 
permissions at the server are not reflected at the client until updates to data that is stored locally by 
the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) 
command determine the time between refresh operations of local data.) Access to a remote file may 
also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote 
systems. 


[EAGAIN] 


Operation would have caused the process to be suspended. 


[EBADNAME] 


The object name specified is not correct. 


[EBUSY] 


Resource busy. 


An attempt was made to use a system resource that is not available at this time. 
[EDAMAGE] 


A damaged object was encountered. 


A referenced object is damaged. The object cannot be used. 
[EFAULT] 


The address used for an argument is not correct. 
In attempting to use an argument in a call, the system detected an address that is not valid. 


While attempting to access a parameter passed to this function, the system detected an address that 
is not valid. 

[EINVAL] 
The value specified for the argument is not correct. 
A function was passed incorrect argument values, or an operation was attempted on an object and 
the operation specified is not supported for that type of object. 
An argument value is not valid, out of range, or NULL. 

[EIO] 


Input/output error. 


A physical I/O error occurred. 


A referenced object may be damaged. 
[EISDIR] 


Specified target is a directory. 
The path specified named a directory where a file or object name was expected. 


The path name given is a directory. 
[ELOOP] 
A loop exists in the symbolic links. 
This error is issued if the number of symbolic links encountered is more than POSIX_S YMLOOP 


(defined in the limits.h header file). Symbolic links are encountered during resolution of the 
directory or path name. 


[EMFILE] 
Too many open files for this process. 
An attempt was made to open more files than allowed by the value of OPEN_MAX. The value of 
OPEN_MAX can be retrieved using the sysconf() function. 
The process has more than OPEN_MAX descriptors already open (see the sysconf() function). 
[ENAMETOOLONG] 
A path name is too long. 
A path name is longer than PATH_MAX characters or some component of the name is longer than 
NAME_MAX characters while _POSIX_NO_TRUNC is in effect. For symbolic links, the length 


of the name string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and 
NAME_MAxX< values can be determined using the pathconf() function. 


[ENFILE] 


Too many open files in the system. 


A system limit has been reached for the number of files that are allowed to be concurrently open in 
the system. 


The entire system has too many other file descriptors already open. 
[ENOENT] 
No such path or directory. 


The directory or a component of the path name specified does not exist. 


A named file or directory does not exist or is an empty string. 
[ENOMEM] 


Storage allocation request failed. 
A function needed to allocate storage, but no storage is available. 


There is not enough memory to perform the requested function. 
[ENOSPC] 


No space available. 


The requested operations required additional space on the device and there is no space left. This 
could also be caused by exceeding the user profile storage limit when creating or transferring 
ownership of an object. 


Insufficient space remains to hold the intended file, directory, or link. 


[ENOSYSRSC] 


System resources not available to complete request. 


[ENOTAVAIL] 


Independent Auxiliary Storage Pool (ASP) is not available. 


The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage (RCLSTG) 
processing. 


To recover from this error, wait until processing has completed for the independent ASP. 


[ENOTDIR] 


Not a directory. 


A component of the specified path name existed, but it was not a directory when a directory was 
expected. 


Some component of the path name is not a directory, or is an empty string. 


[ENOTSAFE] 


Function is not allowed in a job that is running with multiple threads. 


[EUNKNOWN] 


Unknown system state. 


The operation failed because of an unknown system state. See any messages in the job log and 
correct any errors that are indicated, then retry the operation. 


Error Messages 


The following message may be sent from this function: 


Message ID 
CPE3418 E 
CPF3CF2 E 
CPFA0D4 E 
CPF9872 E 


Error Message Text 

Possible APAR condition or hardware failure. 
Error(s) occurred during running of &1 API. 
File system error occurred. Error number &1. 


Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 


1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 


o Where multiple threads exist in the job. 


oO. The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


m Root 

m QOpenSys 

m User-defined 

wg QNTC 

mw QSYS.LIB 

m = Independent ASP QSYS.LIB 
mw QOPT 


2. If the exit program called by Qp0IProcessSubtree() is not threadsafe or uses a function that is not 
threadsafe, then Qp0IProcessSubtree() is not threadsafe. 


3. If the exit program called by Qp0IProcessSubtree() uses a function that fails when there are 
secondary threads active in the job, Qp0IProcessSubtree() may fail as a result. 


4. Basic function and usage considerations 


O QpOlProcessSubtree() does not perform the following tasks but is designed to work with 
the user exit function and other APIs to be useful in accomplishing the following and other 
tasks: 

= Retrieve object attributes (like authorities, dates, or sizes). 

m Build lists from selected objects. 

m Delete directories. 

m Identify multiple occurrences of an object within or across directories. 
7 


Count the number of objects in a directory. 


oO DosSetRelIMaxFH( is called to increase to the maximum the number of file descriptors 
that can be opened during processing such that Qp0IProcessSubtree() is not likely to fail 
due to a lack of descriptors. This value is not reset when Qp0IProcessSubtree() ends 
because the API could be running in a multithreaded job. 


5. Object locking 


Qp0IProcessSubtree() does not perform any object locking, other than what is done when opening 
a directory to read the objects it contains, so that the exit program does not encounter or need to 
manage locks held by Qp0IProcessSubtree(). Once Qp0IProcessSubtree() has started searching a 
path, the addition, deletion, or removal of mounted directories or objects may not have any effect 


on the results of the search. 


If Qp0IProcessSubtree() encounters a directory that is locked, Qp01ProcessSubtree() uses the 
defined Err_recovery_action to determine how to handle the locked condition. Locks on objects 
that are not directories have no effect on Qp0IProcessSubtree(). 


6. Design considerations for parameters 


1. Symbolic links 


When the last component of the path name supplied on the initial call of 
Qp0IProcessSubtree() is a symbolic link, Qp0IProcessSubtree() resolves and follows the 
initial link to its target and performs its normal functions on the target. All other symbolic 
links that are encountered in the same search are not resolved to their targets. 


If the path name supplied on the initial call of Qp0IProcessSubtree() is a symbolic link 
that points to another file system or that points to a remote file system, the API resolves 
and processes the initial link only. It does not resolve other symbolic links that are 
encountered in the same search. However, if the caller specified that remote objects are not 
processed, but the initial path name (whether a symbolic link or not) points to a remote file 
system, the link is not resolved. Qp0IProcessSubtree() calls the exit program with a 
NULL path name and an indicator that Qp0IProcessSubtree() has completed successfully 
without any error indicators to the exit program. 


When *SYMLNK is specified as part of the selection criteria, Qp0IProcessSubtree() does 
not resolve the selected names. 


2. Recovery Actions 


There are three separate parameters that control error recovery during a search. The caller 
of the API determines how an error should be reported to the exit program by setting the 
Err_recovery_actions parameter. The API sets the Selection status pointer and sends it to 
the exit program to indicate one of four conditions: the API search status is OK, the last 
object has been processed, the API has encountered recoverable errors, or the search cannot 
continue. For error conditions it also sends a valid errno. The exit program returns an 
indicator back to the API either to continue or to end the search by setting the Return value 
pointer. For error conditions, it also returns a valid errno, pointed to by the Return value 
pointer. Each time Qp01ProcessSubtree() regains control from the exit program, it 
determines whether the search should continue or end by evaluating the 
Err_recovery_actions parameter, its Selection status pointer, and the Return value pointer. 
Upon ending, Qp0IProcessSubtree() returns 0 to indicate a successful search, or a -1 and 
an errno to indicate the error condition. This errno may have been set by the exit program 
(Return value pointer). 


This error recovery design allows for flexibility in handling errors between the caller, the 
API, and the exit program. Whenever an unrecoverable error occurs, if possible, the exit 
program is given a final call; this call allows the exit program to do such tasks as cleanup 
or to put information in the function control block, or to record information about the error. 
However, the exit program cannot decide that the search should continue. The API will 
return to its caller when it regains control. There are only two specific instances in which 
the API determines that the exit program is not called: 


m When the API cannot resolve the exit program name or its authorization. 


m= When input parameters are missing or specified incorrectly. (The API returns 
EINVAL to the caller before any other processing.) 


Following is a diagram showing the flow and relationship of these parameters. 


Process a 
Path Name 
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Actions slalus 
and 
errno 
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(0,-1, or valid errno} 


Scenarios 


Following are scenarios showing calls and the results of calls to Qp01ProcessSubtree(). Directory 
Structure A and Directory Structure B define the input directory structure for these scenarios. 


Figure: Directory Structure A 


_ (x) (t) 
(y) (Z) 


This directory structure represents three subdirectories (a, b, c), three objects (x, y, z), and a symbolic link 


(t). 


Figure: Directory Structure B 


This directory structure represents six subdirectories (a, b, c, d, e, f) and seven objects (t, u, v, w, X, y, Z). 


Scenario 1 


This scenario assumes processing a directory as shown by Directory Structure A in Figure above. 


This scenario shows a call to the API without any criteria to filter the selection of objects in the path being 
searched. If the API call were coded with the parameter values as shown by Input value in Scenario 1 API 


Input, the exit program would be called nine times and would pass the object names as shown by the Object 
Name Pointer in Results of a call. Because QPOL_SUBTREE_ YES is specified, all of the directories in the 


path will be opened and the name of all the objects that they contain will be passed to the exit program. 
Note that the only guaranteed order is that parent directories are passed to the exit program after all of their 
children. 


Figure: Scenario 1 API Input 


| Input Parameter Input value 


*Path_Name T (/' processes every directory on the system and is not recommended if 
performance is a consideration) 


| Subtree_level | QPOL_SUBTREE_ YES 

| *Objtypes_array_ptr | NULL 

| Local_remote_obj | QPOL_LOCAL_REMOTE_OBJ 
| *IN_EXclusion_ptr | NULL 

| Err_recovery_action | QPOL_PASS_WITH_ERRORID 
| *UserFunction_ptr | QPOL_USER_FUNCTION_PTR 
| *Function_CtlBlk_ptr | NULL 


Figure: Results of a call 


| Exit Program Call Count | Object Name Pointer 
| 1 | /albly 

| 2 /alb 

| 3 | /alx 

| 4 | /alt 

| 5 | /alclz 

| 6 | /alc 


Scenario 2 


This scenario assumes processing a directory as shown by Directory Structure A in the Figure above. 


This shows a call to the API with the Subtree level parameter set to retrieve only one level, without any 
object filtering. Since QPOL_SUBTREE_NO is specified, the names of all objects in the path will be 
passed to the exit program, however, none of the directories will be opened. This allows a caller to perform 
tasks such as identifying all of the root objects for a file system. For example, this would identify all of the 
first level folders, when processing against the QDLS file system. Then the API can be called recursively 
from within the exit program, with each of these folders specified as the path to be searched. 


If the API call were coded with the parameter values as shown by Input value in Scenario 2 API Input, the 
exit program would be called six times and would pass the object names as shown by the Object Name 


Pointer in Results of a call. 


Figure: Scenario 2 API Input 


| Input Parameter | Input value 

| *Path_Name ‘Ta’ 

| Subtree_level | QPOL_SUBTREE NO 

| *Objtypes_array_ptr | NULL 

| Local_remote_obj | QPOL_LOCAL_REMOTE_OBJ 
| *IN_EXclusion_ptr | NULL 

| Err_recovery_action | QPOL_PASS_WITH_ERRORID 
| *UserFunction_ptr | QPOL_USER_FUNCTION_PTR 
| *Function_CtlBlk_ptr | 


Figure: Results of a call 


| Exit Program Call Count | Object Name Pointer 


Scenario 3 


This scenario assumes processing a directory as shown by Directory Structure B in the Figure above. 


This scenario represents a call to the API with an inclusion list. Note that the Path Name parameter is not 
used as the starting directory since each entry in an inclusion list is treated as a starting directory. 


If the API call were coded with the parameter values as shown by Input value in Scenario 3 API Input, the 
exit program would be called six times and would pass the object names as shown by the Object Name 


Pointer in Results of a call. 
Note that /a/b/c/d/v could be returned before /a/b/c/d/u, as shown in this scenario, since children in a 


directory can be returned in any order. The only guaranteed order is that the exit program is called with all 
children objects before being called with the parent to allow the exit program to delete directories if desired. 


Figure: Scenario 3 API Input 


| Input Parameter | Input value 

| *Path_Name | NULL (not used with an inclusion list) 

| Subtree_level | QPOL_SUBTREE_YES 

| *Objtypes_array_ptr | "EDIR | '*STMEF ' 

| Local_remote_obj | QPOL_LOCAL_OBJ 

| *IN_EXclusion_ptr | QPOL_INCLUSION_TYPE, '/a/b/c/d/' '/a/b/c/e/ 
| Err_recovery_action | QPOL_PASS_WITH_ERRORID 

| *UserFunction_ptr | QPOL_USER_FUNCTION_PTR 

| *Function_CtlBlk_ptr | 


Figure: Results of a call 


| Exit Program Call Count | Object Name Pointer 

| 1 | /alb/c/d/v 

| 2 | /alb/c/d/u 

| 3 | /alb/c/d 

| 4 | /alb/cle/w 

| 5 | /alb/cle/ 

| 6 | NULL path name (indicates the API completed) 


Scenario 4 


This scenario assumes processing a directory as shown by Directory Structure B in the Figure above. 


This scenario represents a call to the API with an exclusion list. Note that each relative entry in the 
exclusion list is resolved relative to the current working directory at the time the API is called. This 
scenario assumes that the current working directory is /a/b/. 


If the API call were coded with the parameter values as shown by Input value in Scenario 4 API Input, the 


exit program would be called eight times and would pass the object names as shown by the Object Name 
Pointer in Results of a call. 


This scenario also shows that children in a directory can be returned in any order. The only guaranteed 
order is that the exit program is called with all children objects before being called with the parent to allow 
the exit program to delete directories if desired. 


Figure: Scenario 4 API Input 


| Input Parameter | Input value 

| *Path_Name | ‘Talbi' 

| Subtree_level | QPOL_SUBTREE_YES 

| *Objtypes_array_ptr | "DIR ''*STME ' 

| Local_remote_obj | QPOL_LOCAL_OBJ 

| *IN_EXclusion_ptr QPOL_EXCLUSION_ TYPE, 'c/d/' 'c/e/' 
| Err_recovery_action QPOL_PASS_WITH_ERRORID 

| *UserFunction_ptr QPOL_USER_FUNCTION_PTR 

| *Function_CtlBlk_ptr | NULL 


i 


Figure: Results of a call 


| Exit Program Call Count | Object Name Pointer 
| 1 | /alb/t 

| 2 | /alb/cly 

| 3 | /alb/c/f/z 

| 4 | /alb/c/f 

| 5 | /alb/c/x 


| 6 | /alb/c 
| 7 /alb 


| 8 | NULL path name (indicates the API completed) 


Related Information 


e The <QpOlstdi.h> file (see Header Files for UNIX-Type Functions) 


e The <qlg.h> file (see Header Files for UNIX-Type Functions) 


e QOlgProcessSubtree()--Process a Path Name (using NLS-enabled path name) 


@ = Process a Path Name Exit Program 


Example 


See Code disclaimer information for information pertaining to code examples. 


Following is a code example showing a call to the Qp01ProcessSubtree() API with a procedure as the exit 
program: 


[BRK KKK KK KK KK KKK KK EE KE KK / 
[BRK KKK KR KK KK KK KK KK EK KK / 


#include <Qp0lstdi.h> 
#include <stdio.h> 
#include <errno.h> 
#include <qtqiconv.h> 


void Obj_Print_Function 


(uint *Selection_status_pointer, 

uint *Error_value_pointer, 

uint *Return_value_pointer, 
Qlg_Path_Name_T *Object_name_pointer, 

void *Function_control_block_pointer) 


[BR KKK KKK KK KK KK KK RK I KK KK KK  / 


/* This exit program example prints the names, one at a time, ef 
/* of each entry in a directory structure that it receives on ey 
/* each call from Qp01ProcessSubtree(). */ 


[KR KKK KKK RK KK KK KR I IE RK RK KK KK KK / 


#define PATH TYPE POINTER O0x00000001 /* If this flag is on, */ 
/* the qlg structure contains a */ 
/* pointer to the path name. my 
/* Otherwise, the path name is in */ 
/* contiguous storage within the Ls 


/* glg structure. * / 


typedef union pn_input_type 


{ 


}; 


char pn_char_type[256]; /* path name is in 57 
/* contiguous storage */ 
char *pn_ptr_type; /* path name is a pointer * 


typedef struct pnstruct 


{ 


} 


Qlg_Path_Name_T qlg_struct; 
union pn_input_type pn; 


, 


struct pnstruct *pns; 
char *path_ptr; 


size_t insz; 

size_t outsz = 1000; 
char outbuf[1000]; 
char *outbuf_ptr; 
iconv_t cd; 

size_t ret_iconv; 


QtqCode_T toCode = {37,0,0,0,0,0}; 
QtqCode_T fromCode = {61952,0,0,1,0,0}; 


if 
{ 


( 


if 
{ 


*Selection_status_pointer == QPOL_SELECT_OK) 


(Object_name_pointer != NULL) 


[KR KK KK KK KK I KI I I KK KK / 


/* Point to the pathname and get the size of the pathname oA 


/* that was sent from the Qp01ProcessSubtree() API. The */ 
/* format of the pathname must be determined by evaluating */ 
/* Path_Type in the qlg structure. vA 


[RR KK KK KK KK I I I I IK KK KK / 
pns = (struct pnstruct *)Object_name_pointer; 

if (Object_name_pointer->Path_Type & PATH_TYPE_POINTER) 

{ 


path_ptr = pns-—>pn.pn_ptr_type; 


} 


else 


{ 
path_ptr = (char *) (pns->pn.pn_char_type) ; 


} 
insz = pns->qlg_struct.Path_Length; 


[KKK KKK KK KK I KI I I I KK KK / 


/* Initialize the print buffer. ee: 
[KR KK KK KK KK I KI II KK KK / 
outbuf_ptr = (char *) outbuf; 

memset (outbuf_ptr, 0x00, insz); 


[RR KK KK KK KR KK I KI I IK KK KK / 


/* Use iconv to convert from 61952 to the job CCSID. a): 


/* REMEMBER iconv will change the data that it receives. */ 
[KR KK KK KK KK KI I I I KK KKK / 


cd = /* Open the conversion descriptor.*/ 
QtqIconvOpen (&toCode, 
&fromCode); 
if (cd.return_value == -1) 
{ 
[RK KKK KR KK KK KK KK I KI KE KK KK / 
/* If conversion descriptor was not opened successfully, */ 


/* return an error and errno (ECONVERT) to the API. */ 
[RK KKK KR KK KK KK KK IE I I KK KK / 


*Return_value_pointer = errno; 
return; 
} 

ret_iconv = /* Perform the conversion.*/ 


(iconv (cd, 
(char **)&(path_ptr), 
&insz, 
(char **)&(outbuf_ptr), 
&0utsz)); 
if (ret_iconv != 0) 


{ 


[RK KKK RK KR KK KK I KI I RK KK KK / 


/* If the conversion failed, close the conversion */ 
/* descriptor and return an error and errno (ECONVERT) 273 
/* to the API. * / 


[BRK KK KK KK KR KK KK I I KK KK / 
ret_iconv= iconv_close (cd) ; 

*Return_value_pointer = errno; 

return; 


} 


[KR RK KK KK KK I I EE I KK KK / 


/* Print the name of the object being processed and close *f 


/* the conversion descriptor. x 
[RR KK KK KK KKK I KI I II I KK KK KK / 


printf("In User Exit Program. Path is %s.\n", outbuf); 
ret_iconv = iconv_close(cd); 


} /* end Object_name_pointer != NULL */ 
else 


{ 


printf"In User Exit Program with a null Pathname \n"); 


} 
} /* end *Selection_status_pointer == QPOL_SELECT_OK */ 


*Return_value_pointer = 0; 


} /* end Exit program */ 


int main (int argc, char *argv[]) 
{ 
#define MYPN "/TestDir" 
const int zero = 0; 
const char US_const[3]= "US"; 
const char Language_const [4]="ENU"; 


const char Path_Name_Del_const[2]= "/"; 
const char LibObj_const[12]= "*LIB Ms 
typedef struct pnstruct 
{ 
Qlg_Path_Name_T gqlg_struct; 
char pn[50]; /* Must be greater than */ 


/* or equal the length 


/* of the path name. 
}; 
struct pnstruct pns; 
Qp0l_Objtypes_List_t MyObj_types; 


Qp0l_User_Function_t User_function; 
struct 
{ 
uint AnyData_to_the_exitprogram; 
uint AnyData_not_processed_by_the_APT; 


} Ct1lBlkAreaName; 


int rc; 


at 4 
*/ 


[RK KKK KK KK KK I I I I I RK KK KK / 


/* In this example, the pathname is defined by MYPN as TestDir */ 
/* and it is assumed that the TestDir directory exists on the */ 
/* system. Various other functions or other routines could be */ 


/* included here to (for example): 


/* 1) determine the beginning search directory. 
/* 2) construct the path name in the correct format. 
/* 3) others... 


“ff 
*/ 
xf 
ae 4 


[RK KKK KK KR KK KK I I I I KK KK / 


[RK KK KK KR KK KK I I KK KK / 


[RK KKK RK KR KK KK KI I I II I KK KK / 


/* Initialize Qp01ProcessSubtree() API Parameters 


xf 


[RK KK KK KK KK KK I I I KK KK / 


memset ((void*)&pns, 0x00, sizeof(struct pnstruct)); 
pns.qlg_struct.CCSID = 37; 

memcpy (pns.qlg_struct.Country_ID,US_const, 2); 

memcpy (pns.qlg_struct.Language_ID, Language_const,3); 
pns.qlg_struct.Path_Type = zero; 
pns.qlg_struct.Path_Length = sizeof (MYPN)-1; 


memcpy (pns.pn, MYPN, sizeof (MYPN) ); 
MyObj_types.Number_Of_Objtypes = zero; 


User_function.Function_Type = QPOL_USER_FUNCTION_PTR; 
User_function.Mltthdacn[0] = QPOL_MLTTHDACN_NOMSG; 
User_function.Procedure = &Obj_Print_Function; 


if (rc = Qp01ProcessSubtree((Qlg_Path_Name_T *) &pns, 
QPOL_SUBTREE_YES, 
(Qp01_Objtypes_List_t *)NULL, 
QPOL_ LOCAL _REMOTE_OBJ, 
(Qp01_IN_EXclusion_List_t *)NULL, 
QOPOL_PASS_WITH_ERRORID, 
&User_function, 

&CtlBlkAreaName) == 0) 


{ 


printf ("Qp01ProcessSubtree() Successful : error = $d\n", 


memcpy (pns.qlg_struct.Path_Name_Delimiter, Path_Name_Del_const,1)j; 


memset ((void *)&User_function, 0x00, sizeof (Qp01_User_Function_t)); 


errno); 


} 
else 
{/*unsuccessful return from Qp01ProcessSubtree() API 
printf ("ERROR on Qp01ProcessSubtree(): error = %d\n", 
perror ("Error message"); 
} 


} /* end main */ 


API introduced: V4R3 


Top | UNIX-Type APIs | APIs by category 


a 


errno); 


Qp0IRenameKeep()--Rename File or Directory, 
Keep "new" If It Exists 


Syntax 


#include <Qp0lstdi.h> 


int Qp0lRenameKeep (const char *old, const char *new); 


Threadsafe: Conditional; see Usage Notes. 


The Qp0IRenameKeep() function renames a file or a directory specified by old to the name given by new. 
The old pointer must specify the name of an existing file or directory. Both old and new must be of the 
same type; that is, both directories or both files. o/d and new must not end in "dot" (.) or "dot-dot" (..). 


If new already exists, Qp0IRenameKeep() fails with the [EEXIST] error. 


If the old argument points to a symbolic link, the symbolic link is renamed. Qp0IRenameKeep() does not 
affect any file or directory named by the contents of the symbolic link. #*See Usage Notes for more 


information. *& 


When Qp0IRenameKeep() is successful, it updates the change and modification times for the parent 
directories of old and new. 


If the old object is checked out, Qp0IRenameKeep() fails with the [EBUSY] error. 


Parameters 


old 
(Input) A pointer to the null-terminated path name of the file to be renamed. 
This parameter is assumed to be represented in the CCSID (coded character set identifier) currently 


in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented 
in the default CCSID of the job. 


See QlgRenameKeep()--Rename File or Directory, Keep "new" If It Exists (using NLS-enabled 
path name) for a description and an example of supplying the o/d in any CCSID. 


new 
(Input) A pointer to the null-terminated path name of the new name of the file. 
This parameter is assumed to be represented in the CCSID currently in effect for the job. If the 


CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the 
job. 


The new file name is assumed to be represented in the language and country or region currently in 
effect for the job. 


See QlgRenameKeep()--Rename File or Directory, Keep "new" If It Exists (using NLS-enabled 
path name) for a description and an example of supplying the new in any CCSID. 


Authorities 


Note: Adopted authority is not used. 


Figure 1-57. Authorization Required for Qp0IRenameKeep() (excluding QSYS.LIB, independent 
ASP QSYS.LIB,*® QDLS, and QOPT) 


Authority 
Object Referred to Required |jerrno 
[Each directory in old path name preceding the object to be renamed [*x |EACCES 
[Parent directory of old object [*wx [EACCES 


old object if it is a directory *OBJMGT |EACCES 
| i *W | 


Jold object if it is not a directory |*OBJMGT [EACCES 
[Each directory in new path name preceding the object Px [EACCES 
[Parent directory of new object [*WX [EACCES 


Figure 1-58. Authorization Required for Qp0IRenameKeep() in the QSYS.LIB and #independent 
ASP QSYS.LIB File Systems. 


Authority 
Object Referred to Required |errno 
[Each directory in old path name preceding the object to be renamed [*x [EACCES 
[Parent directory of old object if the object is a database file member |*OBJMGT [EACCES 


Parent directory of the parent directory of old object if the object is a database file |*UPD EACCES 
aoa | | 


Parent directory of new object 


Figure 1-59. Authorization Required for Qp0IRenameKeep() in the QDLS File System 


Ee com 
Object Referred to Required |errno 

[Each directory in o/d path name preceding the object to be renamed [*x [EACCES 
[Parent directory of oldobject = ss—i‘ié.. CRMCHANGEEACCES 
loldobject ALL TEACCES 
[Each directory in new path name preceding the object =————(<i~‘~S~*é~*YCX =~ [EAS 
[Parent directory ofnewobject = ss—‘éC CKCHANGEEACCES 


Figure 1-60. Authorization Required for Qp0IRenameKeep() in the QOPT File System 


Authority 
Object Referred to Required errno 
[Volume authorization list for volume to be renamed in a media library device [*ALL [EACCES 


[Volume authorization list for volume to be renamed in a stand alone device [*CHAN GE [EACCES 
[Volume authorization list for volume containing object to be renamed [*CHAN GE [EACCES 


Root directory (/) of volume to be renamed if volume media format is Universal |*RWX EACCES 
Disk Format (UDF) 
Each directory in old path name preceding the object to be renamed if volume a po 


media format is Universal Disk Format (UDF) 


Parent directory of old object if volume media format is Universal Disk Format *WX EACCES 
fae 


[Old object if volume media format is Universal Disk Format (UDF) ia [EACCES 


Each directory in new path name preceding the object if volume media format is EACCES 
Universal Disk Format (UDF) 

Parent directory of new object if volume media format is Universal Disk format EACCES 
(UDF) 

Object and parent directories if volume media format is not Universal Disk format |None None 
oe 


Return Value 


0 
Qp0IRenameKeep() was successful. 
-] 


Qp0IRenameKeep() was not successful. The errno global variable is set to indicate the error. 


Error Conditions 


If Qp0IRenameKeep() is not successful, errno usually indicates one of the following errors. Under some 
conditions, errno could indicate an error other than those listed here. 


[EACCES] 


Permission denied. 


An attempt was made to access an object in a way forbidden by its object access permissions. 
The thread does not have access to the specified file, directory, component, or path. 


If you are accessing a remote file through the Network File System, update operations to file 
permissions at the server are not reflected at the client until updates to data that is stored locally by 
the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) 
command determine the time between refresh operations of local data.) Access to a remote file may 
also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote 


systems. 


[EAGAIN] 


Operation would have caused the process to be suspended. 
[EBADFID] 

A file ID could not be assigned when linking an object to a directory. 

The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as possible. 


[EBADNAME] 


The object name specified is not correct. 
[EBUSY] 
Resource busy. 


An attempt was made to use a system resource that is not available at this time. 


[ECONVERT] 


Conversion error. 


One or more characters could not be converted from the source CCSID to the target CCSID. 


[EDAMAGE] 


A damaged object was encountered. 


A referenced object is damaged. The object cannot be used. 


[EEXIST] 


File exists. 
The file specified already exists and the specified operation requires that it not exist. 


The named file, directory, or path already exists. 


[EFAULT] 


The address used for an argument is not correct. 


In attempting to use an argument in a call, the system detected an address that is not valid. 


While attempting to access a parameter passed to this function, the system detected an address that 
is not valid. 


[EFILECVT] 


File ID conversion of a directory failed. 


Try to run the Reclaim Storage (RCLSTG) command to recover from this error. 


[EINTR] 


Interrupted function call. 


[EINVAL] 


[EIO] 


The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on an object and 
the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. May be returned if the directories 


preceding the object to be renamed in the o/d path name are part of new, or if either name refers to 
dot or dot-dot. 


Input/output error. 
A physical I/O error occurred. 


A referenced object may be damaged. 


[EISDIR] 


Specified target is a directory. 
The path specified named a directory where a file or object name was expected. 


The path name given is a directory. New is a directory, but old is not a directory. 


#*[EJRNDAMAGE] 


Journal damaged. 


A journal or all of the journal's attached journal receivers are damaged, or the journal sequence 
number has exceeded the maximum value allowed. This error occurs during operations that were 
attempting to send an entry to the journal. 


[EJRNENTTOOLONG] 


Entry too large to send. 


The journal entry generated by this operation is too large to send to the journal. 


[EJRNINACTIVE] 


Journal inactive. 


The journaling state for the journal is *INACTIVE. This error occurs during operations that were 
attempting to send an entry to the journal. 


[EJRNRCVSPC] 


Journal space or system storage error. 


The attached journal receiver does not have space for the entry because the storage limit has been 
exceeded for the system, the object, the user profile, or the group profile. This error occurs during 
operations that were attempting to send an entry to the journal.*& 


[ELOOP] 


A loop exists in the symbolic links. 


This error is issued if the number of symbolic links encountered is more than POSIX_S YMLOOP 
(defined in the limits.h header file). Symbolic links are encountered during resolution of the 
directory or path name. 


[ENAMETOOLONG] 


A path name is too long. 


A path name is longer than PATH_MAX characters or some component of the name is longer than 
NAME_MAX characters while _POSIX_NO_TRUNC is in effect. For symbolic links, the length 
of the name string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and 
NAME_MAX values can be determined using the pathconf() function. 


#[ENEWJRN] 
New journal is needed. 
The journal was not completely created, or an attempt to delete it did not complete successfully. 


This error occurs during operations that were attempting to start or end journaling, or were 
attempting to send an entry to the journal. 


[ENEWJRNRCV] 
New journal receiver is needed. 
A new journal receiver must be attached to the journal before entries can be journaled. This error 


occurs during operations that were attempting to send an entry to the journal.“ 


[ENOENT] 
No such path or directory. 


The directory or a component of the path name specified does not exist. 


A named file or directory does not exist or is an empty string. 


[ENOMEM] 


Storage allocation request failed. 
A function needed to allocate storage, but no storage is available. 


There is not enough memory to perform the requested function. 


[ENOSPC] 
No space available. 
The requested operations required additional space on the device and there is no space left. This 
could also be caused by exceeding the user profile storage limit when creating or transferring 
ownership of an object. 


Insufficient space remains to hold the intended file, directory, or link. 


[ENOTAVAIL] 
Independent Auxiliary Storage Pool (ASP) is not available. 


The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage (RCLSTG) 
processing. 


To recover from this error, wait until processing has completed for the independent ASP. 


[ENOTDIR] 


Not a directory. 


A component of the specified path name existed, but it was not a directory when a directory was 
expected. 


Some component of the path name is not a directory, or is an empty string. 


[ENOTSAFE] 


Function is not allowed in a job that is running with multiple threads. 
[ENOTSUP] 
Operation not supported. 
The operation, though supported in general, is not supported for the requested object or the 


requested arguments. 


[EMLINK] 


Maximum link count for a file was exceeded. 


An attempt was made to have the link count of a single file exceed LINK_MAX. The value of 
LINK_MAxX can be determined using the pathconf() or the fpathconf() function. 


old is a directory and the link count of the parent directory of new would exceed LINK_MAX. 


[EPERM] 
Operation not permitted. 


You must have appropriate privileges or be the owner of the object or other resource to do the 
requested operation. 


[EROOBJ] 
Object is read only. 


You have attempted to update an object that can be read only. 


[ESTALE] 
File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may have been deleted 
at the server. 


[EUNKNOWN] 
Unknown system state. 


The operation failed because of an unknown system state. See any messages in the job log and 
correct any errors that are indicated, then retry the operation. 


[EXDEV] 


Improper link. 
A link to a file on another file system was attempted. 


old and new identify files or directories in different file systems. Links between different file 
systems are not allowed. 


If interaction with a file server is required to access the object, errno could also indicate one of the 
following errors: 
[EADDRNOTAVAIL] 

Address not available. 
[ECONNABORTED] 

Connection ended abnormally. 
[ECONNREFUSED] 

The destination socket refused an attempted connect operation. 
[ECONNRESET] 

A connection with a remote socket was reset by that socket. 
[EHOSTDOWN] 

A remote host is not available. 
[EHOSTUNREACH] 

A route to the remote host is not available. 
[ENETDOWN] 


The network is not currently available. 
[ENETRESET] 

A socket is connected to a host that is no longer available. 
[ENETUNREACH] 

Cannot reach the destination network. 
[ETIMEDOUT] 

A remote host did not respond within the timeout period. 
[EUNATCH] 


The protocol required to support the specified address family is not available at this time. 


Error Messages 


The following messages may be sent from this function: 
CPE3418 E 

Possible APAR condition or hardware failure. 
CPFAO0D4 E 

File system error occurred. Error number &1. 
CPF3CF2 E 

Error(s) occurred during running of &1 API. 
CPF9872 E 


Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 


1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 
oO Where multiple threads exist in the job. 


oO The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


m Root 

m QOpenSys 

m User-defined 

wg QNTC 

mw QSYS.LIB 

m {Independent ASP QSYS.LIB & 
mw QOPT 


2. About the Rename Functions 


The integrated file system provides two functions that rename a file or directory. Both rename the 
old path name to a new path name. The difference is determined by what happens when new 
already exists: 


o. If new already exists when using Qp0IRenameKeep(), the rename fails with the [EEXIST] 
error. 


oO If new already exists when using Qp0IRenameUnlink(), the existing path name is 
unlinked (removed) before old is renamed to new. 


These functions are defined in the <QpOlIstdi.h> header file. When <QpOlstdi.h> is included, the 
rename() function is defined to be either Qp0IRenameUnlink() or Qp0IRenameKeep(), 
depending on the definitions of the _POSIX_SOURCE and _POSIX1_SOURCE macros: 


Oo When _POSIX SOURCE and _POSIX1_ SOURCE are not defined, rename() is defined to 
be Qp0IRenameKeep(). Either rename() or Qp0IRenameKeep() can be used to rename a 
file or directory with the semantics of Qp0IRenameKeep(). 


o When _POSIX_ SOURCE or _POSIX1 SOURCE is defined, rename() is defined to be 
Qp0IRenameUnlink(). Either rename() or Qp0IRenameUnlink() can be used to rename a 
file or directory with the semantics of Qp0IRenameUnlink(). 


When the <Qp0lIstdi.h> header file is not included, rename() operates only on database files in the 
QSYS.LIB and # independent ASP QSYS.LIB file systems, “as it did before the introduction of 
the integrated file system. 


. QSYS.LIB and #Independent ASP QSYS.LIB *&File System Differences 


oO When a database member is being renamed, the part of the new path name preceding the 
object must be the same as that of the o/d path name. That is, the sequence of "directories" 
(library and file) preceding the object in the new path name must be the same as the 
sequence of directories preceding the object in the o/d path name. 


oO The following object types cannot be renamed when there are secondary threads active in 
the job: *CFGL, *CNNL, *CTLD, *DEVD, *LIND, *NWID. The operation will fail with 
error code [ENOTSAFE]. 


oO #When a library is being renamed, the part of the new path name preceding the object 
must be the same as that of the old path name. That is, the sequence of "directories" 
(/QSYS.LIB or /asp_name/QSYS.LIB, where asp_name is the independent Auxiliary 
Storage Pool name) preceding the object in the new path name must be the same as the 
sequence of directories preceding the object in the old path name [EINVAL].*& 

. QDLS File System Differences 

When a folder is being renamed, the part of the new path name preceding the object must be the 

same as that of the old path name. That is, a folder must remain in the same parent folder. 


. QOPT File System Differences 


You can rename only a volume or a file, not a directory. 


. QFileSvr.400 File System Differences 
You cannot rename the first-level directory. For example, you cannot rename Dirl in the path name 


/QFileSvr.400/Dir1/Dir2/Object. The first-level directory identifies the target system in a 
communications connection. 


. QNetWare File System Differences 


The new and old files or directories must exist on the same NetWare server. This function cannot 
be used to move data from one server to another. 


8. QNTC File System Differences 


The new and the old files or directories must exist on the same Windows NT server. This function 
cannot be used to move data from one server to another. 


9. #Root (/) and User-defined File System Differences 


If the file being renamed is in the root file system or in a monocase user-defined file system, and 
the file system has the *T'YPE2 directory format, and both old and new refer to the same link, but 
their case is different (eg. /ABC and /Abc), QpO0IRenameUnlink() changes the link name to the new 
name.*& 


Related Information 


e The <stdio.h> file (see Header Files for UNIX-Type Functions) 


e The <Qp0lstdi.h> file (see Header Files for UNIX-Type Functions) 
e@ pathconf()--Get Configurable Path Name Variables 


@ rename()--Rename File or Directory 


e QlgRenameKeep()--Rename File or Directory, Keep "new" If It Exists (using NLS-enabled path 
name) 


e@ Qp0lRenameUnlink()--Rename File or Directory, Unlink "new" If It Exists 


Example 


When you pass two file names to this example, it will try to change the file name from the first name to the 
second using Qp0IRenameKeep(). 


#include <Qp0lstdi.h> 
int main(int argc, char ** argv ) { 
if ( arge != 3 ) 
printf( "Usage: %s old_fn new_fn\n", argv[0] ); 
else if ( Qp0lRenameKeep( argv[1], argv[2] ) != 0 
perror ( "Could not rename file" ); 


} 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


Qp0!IRenameUnlink()--Rename File or Directory, 
Unlink "new" If It Exists 


Syntax 


#include <Qp0lstdi.h> 


int Qp01lRenameUnlink (const char *old, const char *new); 


Threadsafe: Conditional; see Usage Notes. 


The Qp0IRenameUnlink() function renames a file or a directory specified by old to the name given by 
new. The old pointer must specify the name of an existing file or directory. Both old and new must be of the 
same type; that is, both directories or both files. o/d and new must not end in "dot" (.) or "dot-dot" (..). 


If new already exists, it is removed before old is renamed to new. Therefore, if new specifies the name of an 
existing directory, the directory must be empty. 


If the old argument points to a symbolic link, the symbolic link is renamed. If the new argument points to a 
symbolic link, the link is removed and o/d is renamed to new. Qp0IRenameUnlink() does not affect any 
file or directory named by the contents of the symbolic link. 


If old and new both refer to the same file, Qp0IRenameUnlink() returns successfully and performs no 
other action. #*See Usage Notes for more information.*& 


When Qp0IRenameUnlink() is successful, it updates the change and modification times for the parent 
directories of old and new. 


If the old object is checked out, Qp0IRenameUnlink() fails with the [EBUSY] error. 


Parameters 


old 
(Input) A pointer to the null-terminated path name of the file to be renamed. 
This parameter is assumed to be represented in the CCSID (coded character set identifier) currently 


in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented 
in the default CCSID of the job. 


See QlgRenameUnlink()--Rename File or Directory, Unlink "new" If It Exists (using NLS-enabled 
path name) for a description and an example of supplying the o/d in any CCSID. 


(Input) A pointer to the null-terminated path name of the new name of the file. 


This parameter is assumed to be represented in the CCSID currently in effect for the job. If the 
CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the 
job. 


The new file name is assumed to be represented in the language and country or region currently in 
effect for the process. 


See QlgRenameUnlink()--Rename File or Directory, Unlink "new" If It Exists (using NLS-enabled 
path name) for a description and an example of supplying the new in any CCSID. 


Authorities 


Note: Adopted authority is not used. 


Figure 1-61. Authorization Required for Qp0IRenameUnlink() (excluding QSYS.LIB, “independent 
ASP QSYS.LIB, *SQDLS, and QOPT) 


Authority 
Object Referred to Required errno 
[Each directory in old path name preceding the object to be renamed [*x [EACCES 
[Parent directory of old object [*wX |EACCES 


old object if it is a directory *OBJMGT |EACCES 
| i *W | 


fold objectifitisnotadirectory = ssi‘; OS XOBIMGT [EACCES 
[Each directory in new path name preceding the object = s—<~*é‘;:*é~*iSX~=—s [EAC 
[Parent directory ofnewobject = siti‘; CRW XL CLEACCES 
[New object ifitexisss —tititi‘™SOSOSO;!”!C!*;*;*;*;*;*;C;C*C*CdROBXIST [EACCCES 


Figure 1-62. Authorization Required for Qp0IRenameUnlink() in the QSYS.LIB and “independent 
ASP QSYS.LIB File Systems * 


Authority 
Object Referred to Required |errno 
[Each directory in old path name preceding the object to be renamed [*x [EACCES 
[Parent directory of old object if the object is a database file member [*OBJMGT [EACCES 


Parent directory of the parent directory of old object if the object is a database file |*UPD EACCES 
foe | | 


Parent directory of old object if the object is not a database file member See the EACCES 


Parent directory of new object 


Figure 1-63. Authorization Required for Qp0IRenameUnlink() in the QDLS File System 


re nnn ge 
Object Referred to Required |errno 

[Each directory in old path name preceding the objecttobe renamed =————«*WCKX-—s—s [EAC 
[Parent directory of oldobject =——itst—“‘ié;OO!!!!!!.. RCHANGEEACCES 
Joldobject ALL TEACCES. 
[Each directory in new path name preceding the object ==s—<‘~‘~*~*s~WX~—Ss« [EAS 
[Parent directory ofnewobject == s—itsi‘éO!.... CHANGE EACCES 


Figure 1-64. Authorization Required for Qp0IRenameUnlink() in the QOPT File System 


pees tis 
Object Referred to Required errno 

[Volumetoberenamed —ss—i‘“‘“—<‘“‘“‘is™ ALL TRACCES 
[Volume containing object to be renamed *CHANGE [EACCES 
[Object within volume ———ss—s—‘“‘ié None [None 


Return Value 


0) 
Qp0IRenameUnlink() was successful. 
-1 
Qp0IRenameUnlink() was not successful. The errno global variable is set to indicate the error. 


Error Conditions 


If Qp0IRenameUnlink() is not successful, errno usually indicates one of the following errors. Under some 
conditions, errno could indicate an error other than those listed here. 
[EACCES] 


Permission denied. 
An attempt was made to access an object in a way forbidden by its object access permissions. 
The thread does not have access to the specified file, directory, component, or path. 


If you are accessing a remote file through the Network File System, update operations to file 
permissions at the server are not reflected at the client until updates to data that is stored locally by 
the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) 
command determine the time between refresh operations of local data.) Access to a remote file may 
also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote 
systems. 


[EAGAIN] 


Operation would have caused the process to be suspended. 
[EBADFID] 

A file ID could not be assigned when linking an object to a directory. 

The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as possible. 


[EBADNAME] 


The object name specified is not correct. 
[EBUSY] 
Resource busy. 


An attempt was made to use a system resource that is not available at this time. 


[ECONVERT] 


Conversion error. 


One or more characters could not be converted from the source CCSID to the target CCSID. 


[EDAMAGE] 


A damaged object was encountered. 


A referenced object is damaged. The object cannot be used. 


[EEXIST] 


File exists. 
The file specified already exists and the specified operation requires that it not exist. 


The named file, directory, or path already exists. 


[EFAULT] 


The address used for an argument is not correct. 
In attempting to use an argument in a call, the system detected an address that is not valid. 
While attempting to access a parameter passed to this function, the system detected an address that 


is not valid. 


[EFILECVT] 


File ID conversion of a directory failed. 


Try to run the Reclaim Storage (RCLSTG) command to recover from this error. 


[EINTR] 


Interrupted function call. 
[EINVAL] 
The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on an object and 
the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. May be returned if the directories 


preceding the object to be renamed in the o/d path name are part of new, or if either name refers to 
dot or dot-dot. 


[EIO] 


Input/output error. 
A physical I/O error occurred. 


A referenced object may be damaged. 


[EISDIR] 


Specified target is a directory. 
The path specified named a directory where a file or object name was expected. 


The path name given is a directory. New is a directory, but old is not a directory. 


#[EJRNDAMAGE] 
Journal damaged. 
A journal or all of the journal's attached journal receivers are damaged, or the journal sequence 


number has exceeded the maximum value allowed. This error occurs during operations that were 
attempting to send an entry to the journal. 


[EJRNENTTOOLONG] 
Entry too large to send. 


The journal entry generated by this operation is too large to send to the journal. 


[EJRNINACTIVE] 
Journal inactive. 
The journaling state for the journal is *INACTIVE. This error occurs during operations that were 


attempting to send an entry to the journal. 


[EJRNRCVSPC] 


Journal space or system storage error. 


The attached journal receiver does not have space for the entry because the storage limit has been 
exceeded for the system, the object, the user profile, or the group profile. This error occurs during 
operations that were attempting to send an entry to the journal.*& 


[ELOOP] 


A loop exists in the symbolic links. 


This error is issued if the number of symbolic links encountered is more than POSIX_S YMLOOP 
(defined in the limits.h header file). Symbolic links are encountered during resolution of the 
directory or path name. 


[ENAMETOOLONG] 


A path name is too long. 


A path name is longer than PATH_MAX characters or some component of the name is longer than 
NAME_MAX characters while POSIX_NO_TRUNC is in effect. For symbolic links, the length 
of the name string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and 
NAME_MAX values can be determined using the pathconf() function. 


2(ENEWJRN] 


New journal is needed. 


The journal was not completely created, or an attempt to delete it did not complete successfully. 
This error occurs during operations that were attempting to start or end journaling, or were 
attempting to send an entry to the journal. 


[ENEWJRNRCV] 
New journal receiver is needed. 
A new journal receiver must be attached to the journal before entries can be journaled. This error 


occurs during operations that were attempting to send an entry to the journal.*& 


[ENOTAVAIL] 
Independent Auxiliary Storage Pool (ASP) is not available. 


The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage (RCLSTG) 
processing. 


To recover from this error, wait until processing has completed for the independent ASP. 
[ENOTEMPTY] 


Directory not empty. 


You tried to remove a directory that is not empty. A directory cannot contain objects when it is 
being removed. 


The specified directory is not empty. 


[ENOENT] 


No such path or directory. 
The directory or a component of the path name specified does not exist. 


A named file or directory does not exist or is an empty string. 


[ENOMEM] 


Storage allocation request failed. 
A function needed to allocate storage, but no storage is available. 


There is not enough memory to perform the requested function. 


[ENOSPC] 
No space available. 
The requested operations required additional space on the device and there is no space left. This 
could also be caused by exceeding the user profile storage limit when creating or transferring 
ownership of an object. 


Insufficient space remains to hold the intended file, directory, or link. 


[ENOTDIR] 


Not a directory. 


A component of the specified path name existed, but it was not a directory when a directory was 
expected. 


Some component of the path name is not a directory, or is an empty string. 


[ENOTSAFE] 


Function is not allowed in a job that is running with multiple threads. 
[ENOTSUP] 
Operation not supported. 
The operation, though supported in general, is not supported for the requested object or the 


requested arguments. 


[EMLINK] 


Maximum link count for a file was exceeded. 


An attempt was made to have the link count of a single file exceed LINK_MAX. The value of 
LINK_MAX can be determined using the pathconf() or the fpathconf() function. 


old is a directory and the link count of the parent directory of new would exceed LINK_MAX. 


[EPERM] 


Operation not permitted. 


You must have appropriate privileges or be the owner of the object or other resource to do the 
requested operation. 


[EROOBJ] 
Object is read only. 


You have attempted to update an object that can be read only. 


[ESTALE] 
File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may have been deleted 
at the server. 


[EUNKNOWN] 
Unknown system state. 


The operation failed because of an unknown system state. See any messages in the job log and 
correct any errors that are indicated, then retry the operation. 


[EXDEV] 


Improper link. 
A link to a file on another file system was attempted. 


old and new identify files or directories on different file systems. Links between different file 
systems are not allowed. 


If interaction with a file server is required to access the object, errno could also indicate one of the 
following errors: 
[EADDRNOTAVAIL] 
Address not available. 
[ECONNABORTED] 
Connection ended abnormally. 
[ECONNREFUSED] 
The destination socket refused an attempted connect operation. 
[ECONNRESET] 
A connection with a remote socket was reset by that socket. 
[EHOSTDOWN] 
A remote host is not available. 
[EHOSTUNREACH] 
A route to the remote host is not available. 
[ENETDOWN] 
The network is not currently available. 
[ENETRESET] 


A socket is connected to a host that is no longer available. 
[ENETUNREACH] 

Cannot reach the destination network. 
[ETIMEDOUT] 

A remote host did not respond within the timeout period. 
[EUNATCH] 


The protocol required to support the specified address family is not available at this time. 


Error Messages 


The following messages may be sent from this function: 
CPE3418 E 

Possible APAR condition or hardware failure. 
CPFAO0D4 E 

File system error occurred. Error number &1. 
CPF3CF2 E 

Error(s) occurred during running of &1 API. 
CPF9872 E 


Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 


1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 
oO Where multiple threads exist in the job. 


o The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


m Root 

m QOpenSys 

m User-defined 

wg QNTC 

mw QSYS.LIB 

m “Independent ASP QSYS.LIB %& 
mw QOPT 


2. About the Rename Functions 


The integrated file system provides two functions that rename a file or directory. Both rename the 
old path name to a new path name. The difference is determined by what happens when new 
already exists: 


oO If new already exists when using Qp0IRenameUnlink(), the existing path name is 
unlinked (removed) before old is renamed to new. 


oO If new already exists when using Qp0IRenameKeep(), the rename fails with the [EEXIST] 
error. 


These functions are defined in the <QpOIstdi.h> header file. When <QpOlstdi.h> is included, the 
rename() function is defined to be either Qp0IRenameUnlink() or Qp0IRenameKeep(), 
depending on the definitions of the _POSIX_SOURCE and _POSIX1_SOURCE macros: 


o When _POSIX_ SOURCE or _POSIX1 SOURCE is defined, rename() is defined to be 
Qp0IRenameUnlink(). Either rename() or Qp0IRenameUnlink() can be used to rename a 
file or directory with the semantics of Qp0IRenameUnlink(). 


o When _POSIX_ SOURCE and _POSIX1_ SOURCE are not defined, rename() is defined to 
be QpO0IRenameKeep(). Either rename() or Qp0IRenameKeep() can be used to rename a 
file or directory with the semantics of Qp0IRenameKeep(). 


When the <Qp0lstdi.h> header file is not included, rename() operates only on database files in the 
QSYS.LIB and # independent ASP QSYS.LIB file systems, “Kas it did before the introduction of 
the integrated file system. 


. QSYS.LIB and #Independent ASP QSYS.LIB *&File System Differences 


oO When a database member is being renamed, the part of the new path name preceding the 
object must be the same as that of the o/d path name. That is, the sequence of "directories" 
(library and file) preceding the object in the new path name must be the same as the 
sequence of directories preceding the object in the old path name. If new already exists, 
#?[EEXIST] is returned.4& 


oO The following object types cannot be renamed when there are secondary threads active in 
the job: *CFGL, *CNNL, *CTLD, *DEVD, *LIND, *NWID. The operation will fail with 
error code [ENOTSAFE]. 


oO #When a library is being renamed, the part of the new path name preceding the object 
must be the same as that of the old path name. That is, the sequence of "directories" 
(/QSYS.LIB or /asp_name/QS YS.LIB, where asp_name is the independent Auxiliary 
Storage Pool name) preceding the object in the new path name must be the same as the 
sequence of directories preceding the object in the old path name. *& 


. QDLS File System Differences 


When a folder is being renamed, the part of the new path name preceding the object must be the 
same as that of the old path name. That is, a folder must remain in the same parent folder. 


If the object identified by the new path name exists, QDLS returns the [EEXIST] error. 


. QOPT File System Differences 
You can rename only a volume or a file, not a directory. 


If the object identified by the new path name exists, QOPT returns the [EEXIST] error. 


. QFileSvr.400 File System Differences 


You cannot rename the first-level directory. For example, you cannot rename Dirl in the path name 
/QFileSvr.400/Dir1/Dir2/Object. The first-level directory identifies the target system in a 
communications connection. 


7. QNetWare File System Differences 


The new and old files or directories must exist on the same NetWare server. This function cannot 
be used to move data from one server to another. 


8. QNTC File System Differences 


The new and the old files or directories must exist on the same Windows NT server. This function 
cannot be used to move data from one server to another. 


9. #Root (/) and User-defined File System Differences 


If the file being renamed is in the root file system or in a monocase user-defined file system, and 
the file system has the *TYPE2 directory format, and both old and new refer to the same link, but 
their case is different (eg. /ABC and /Abc), QpO0IRenameUnlink() changes the link name to the new 
name.*& 


Related Information 


e The <stdio.h> file (see Header Files for UNIX-Type Functions) 


e The <QpOlstdi.h> file (see Header Files for UNIX-Type Functions) 
e@ pathconf()--Get Configurable Path Name Variables 


@ rename()--Rename File or Directory 


e Qp0lRenameKeep()--Rename File or Directory, Keep "new" If It Exists 


e@ QlgRenameUnlink()--Rename File or Directory, Unlink "new" If It Exists (using NLS-enabled path 
name 


Example 


When you pass two file names to this example, it will try to change the file name from the first name to the 
second using Qp0IRenameUnlink(). 


#include <Qp0Olstdi.h> 
int main(int argc, char ** argv ) { 


if ( arge != 3 ) 
printf( "Usage: %s old_fn new_fn\n", argv[0] ); 
else if ( Qp01lRenameUnlink( argv[1], argv[2] ) != 
perror ( "Could not rename file" ); 


0 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


»Retrieve Object References (QPOLROR) API 


Syntax 


#include <qp0Olror.h> 

void QPOLROR ( 
void * Receiver_Ptr, 
unsigned int Receiver_Length, 
char * Format_Ptr, 
Qlg_Path_Name_T * Path_Ptr, 
void * Error_Code_Ptr 
); 

Default Public Authority: *USE 


Threadsafe: Yes 


The QPOLRORQ( API is used to retrieve information about Integrated File System references on an object. 


A reference is an individual type of access or lock obtained on the object when using Integrated File System 
interfaces. An object may have multiple references concurrently held, provided that the reference types do 
not conflict with one another. 


This API will not return information about byte range locks that may currently be held on an object. 


Parameters 


Receiver_Ptr 
(Output) 


The variable that is to receive the information requested. You can specify the size of this area to be 
smaller than the format requested as long as you specify the length parameter correctly. As a result, 
the API returns only the data that the area can hold. 


The format of the output is described by either the ROROO100 output format or the ROROO200 
output format. See ROROO100 Output Format Description or the ROROO200 Output Format 


Description for a detailed description of these output formats. 


Receiver_Length 
(Input) 
The length of the receiver variable. If the length is larger than the size of the receiver variable, the 
results may not be predictable. The minimum length is 8 bytes. 
Format_Ptr 
(Input) 


Pointer to an 8-byte character string that identifies the desired output format. It must be one of the 
following values: 


ROROOIO0 The reference type output will be formatted ina ROROO100 format. See 
ROROO100 Output Format Description. This format gives the caller a quick view 
of the object's references. 


ROROO200 _ The reference type output will be formatted in a ROROO200 format. See 
ROROO200 Output Format Description. Specifying this format may cause 
QPOLROR to be a long running operation. The length of time it will take to 
complete depends on the number of jobs active on the system, and the number of 
jobs currently using objects through Integrated File System interfaces. 


Path_Ptr 
(Input) 
Pointer to the path name to the object whose reference information is to be obtained. The path name 


must be specified in an NLS-enabled format specified by the Qlg_Path_Name structure. For more 
information on the Qlg_ Path_Name_T structure, see Path name format. 


If the last element of the path is a symbolic link, the Qp0IRORQ() function does not resolve the 
contents of the symbolic link. The reference information will be obtained for the symbolic link 
itself. 


Error_Code_Ptr 
(Input/Output) 


Pointer to an error code structure to receive error information. See Error code parameter for more 
information. 


Authorities and Locks 


Directory Authority 


The user must have execute (*X) data authority to each directory preceding the object whose 
references are to be obtained. 


Object Authority 


The user must have read (*R) data authority to the object whose references are to be obtained. 


Output Structure Formats 


ROROO100 Output Format Description (Qp0/_RORO0100_Output) 


This structure is used to return object reference information. 


| Offset 
ae | Hex Type Field 


| | [BINARY (4), UNSIGNED [Bytes returned 
| 4 | 4 [BINARY(4), UNSIGNED [Bytes available 
| 8 | 8 [BINARY (4), UNSIGNED [Offset to simple reference types 


| 12 | Te [BINARY(4), UNSIGNED [Length of simple reference types 
| 16 | 10 [BINARY(4), UNSIGNED [Reference count 
| 20 | 14 [BINARY(4), UNSIGNED [In-use indicator 


Offset determined Qp0l_Sim_Ref_Types_Output |Simple reference types structure. See Simple 
from Offset to Simple |Structure object reference types structure description for a 


Reference Types field description of this structure. 


ROROO200 Output Format Description (Qp0/_RORO0200_Output) 


This output format is used to return object reference information, including a list of jobs known to be 
referencing the object. This includes everything from the ROROO100 structure plus additional information. 


| Offset 
| D | Hex Type Field 


Io — [0 — BINARY), UNSIGNED — [Bytes sumed 
[ 4 | 4  |BINARY(4), UNSIGNED [Bytesavailable = ss—S 
[ 8 | 8  |BINARY(4),UNSIGNED  |Referencecount. = —ss—S 
[ 12 | OC |BINARY(4),UNSIGNED |In-useindicator =——ss—sS 
[ 16 | 10 |BINARY(4), UNSIGNED [Offset to simple reference types 
[| 20 | 14  |BINARY(4), UNSIGNED [Length of simple reference types 
[ 24 | 18  |BINARY(4), UNSIGNED — [Offset to extended reference types 
[ 28 | 1C  |BINARY(4), UNSIGNED [Length ofextended reference types 
[ 32 | 20  |BINARY(4), UNSIGNED [Offsettojoblist = 
[ 36 | 24 JBINARY(4),UNSIGNED  |Jobsretuned = 
[ 40 | 28 BINARY(4),UNSIGNED § [Jobsavailable = s—s—S 


Offset determined QpOl_Sim_Ref_Types_Output |Simple reference types structure. See Simple 
from Offset to simple |Structure object reference types structure description for a 
reference types field description of this structure. 


Offset determined 
from the Offset to 
Extended Reference 
Types field 


QpOl_Ext_Ref_Types_Output |Extended reference types structure. See Extended 
Structure object reference types structure description for a 


description of this structure. The reference counts 
contained within this structure represent the 
number of references for all jobs in the job list. 


Offset determined Qp0l_Job_Using Object Referencing job list. The Job using object structure 
from Offset to Job —_|Structure will be repeated for each job. 


List field 


Job Using Object Structure Description (Qp0/_Job_Using_Object) 


This structure is imbedded within the ROROO200 format. It is used to return information about a job that is 
known to be holding a reference on the object. 


[ Offet [|  . °+| | 


[ Dee [| Hex |Type IField 

| 0 | 0 [BINARY(4), UNSIGNED [Displacement to simple reference types 

| 4 | 4 [BINARY(4), UNSIGNED [Length of simple reference types 

| 8 | 8 [BINARY(4), UNSIGNED [Displacement to extended reference types 
| 12 | OC [BINARY(4), UNSIGNED [Length of extended reference types 

| 16 | 10 [BINARY(4), UNSIGNED [Displacement to next job entry 

| 20 | 14 CHAR(10) [Job name 

| 30 | 1E [CHAR(10) [Job user 

| 40 | 28 [CHAR(6) [J ob number 


Offset determined Qp0l_Sim_Ref_Types_Output |Simple reference types structure. See Simple 


Structure object reference types structure description for a 
description of this structure. 


Offset determined QpOl_Ext_Ref_Types_Output |Extended reference types structure. See Extended 
from the Structure object reference types structure description for a 


description of this structure. The reference counts 
contained within this structure represent the 
number of references for this specific job. 


Displacement to 
Extended Reference 
Types field 


Simple Object Reference Types Structure Description 
(Qp0L_Sim_Ref_Types_Output) 


This structure is imbedded within the ROROO100 and ROROO200 formats. It is used to return object 
reference type information. 


Each binary field reference type will be set to either 0 or a positive value that represents the number of 
references for that type. This number will have different meanings depending on the structure it is 
imbedded within. When this structure is imbedded within a ROROO100 output, or imbedded within the 
header portion of the ROROO200 output, then these values represent the number of known references of 
this type. When this structure is imbedded within a specific job list entry, then these values represent the 
number of references for that specific type within that specific job itself. 


| Offset 
; D | Hex /Type Field 


=e es BINARY(4), UNSIGNED |[Readonly  —sss—‘“—sSS 
[4 | 4  |BINARY(4),UNSIGNED  [Writeonly = ss—i‘—s~™SCOCS 
[ 8 | 8  |BINARY(4),UNSIGNED |Read/write = ss ss—<—Ss 
[ 12 | OC |BINARY(4),UNSIGNED [Execute = ——ss—‘“‘—sSS 
[ 16 | 10 J{BINARY(4), UNSIGNED [Share withreadersonly = 
[ 20 | 14  |BINARY(4), UNSIGNED [Share with writersonly 
[ 24 | 18  |BINARY(4), UNSIGNED [Share with readers and writers 
[| 28 | IC |BINARY(4), UNSIGNED [Share with neither readers nor writers 
[ 32 | 20 J|BINARY(4),UNSIGNED  [Attributelock = =——ss—i‘“—~;i‘is~™ 
[ 36 | 24 JBINARY(4),UNSIGNED [Savelochk = = = = = ———“<i‘“‘:~C™S™~™~C~™ 


[48 | 30 |BINARY@), UNSIGNED |Checkedout —=—=S=~S~*~“s—sS*~*~*~*~S~S~S~S 
[52 | 34 |GHARGO) |Checkedoutusername—~S~S~*~S~S~S 


Extended Object Reference Types Structure Description 
(Qp0l_Ext_Ref_Types_Output) 


This structure is imbedded within the ROROO200 format. It is used to return object reference type 
information. 


Each binary field reference type will be set to either 0 or a positive value that represents the number of 
references for that type. This number will have different meanings depending on the structure it is 
imbedded within. When this structure is imbedded within the header portion of the ROROO200 output, then 
these values represent the number of jobs in the job list that contains a reference of this type. When this 
structure is imbedded within a specific job list entry, then these values represent the number of references 
for that specific type within that specific job itself. 


| Offset 
a Hex /Type Field 


| 0  |BINARY(4), UNSIGNED BINARY(4), [BINARY(4), UNSIGNED VED [Read only, share with readers only [Read only, share with readers only share with readers only 
| 4  |BINARY(4), UNSIGNED [Read only, share with writers only 
8 [ 8  |BINARY(4), UNSIGNED [Read only, share with readers and writers 
[ 12 | 0C  |BINARY(4), UNSIGNED [Read only, share with neither readers nor writers 
[ 16 | 10  |BINARY(4), UNSIGNED [Write only, share withreadersonly = 
[ 20 | 14  |BINARY(4), UNSIGNED [Write only, share with writers only = 
[ 24 | 18  |BINARY(4), UNSIGNED [Write only, share with readers and writers 
[ 28 | 1C  |BINARY(4), UNSIGNED [Write only, share with neither readers nor writers — 
[ 32 | 20  |BINARY(4), UNSIGNED — [Read/write, share with readers only 
| 36 | 24  |BINARY(4), UNSIGNED — [Read/write, share with writers only = 
[| 40 | 28  |BINARY(4), UNSIGNED — [Read/write, share with readers and writers 
[ 44 | 2C  |BINARY(4), UNSIGNED — [Read/write, share with neither readers nor writers — 
[ 48 | 30  |BINARY(4), UNSIGNED — [Execute, share withreadersonly 
| 52 | 34  |BINARY(4), UNSIGNED — [Execute, share with writers only = 
[ 56 | 38  {BINARY(4), UNSIGNED  [Execute, share with readers and writers 
[ 60 | 3C  |BINARY(4), UNSIGNED — [Execute, share with neither readers nor writers 
| 64 | 40  |BINARY(4), UNSIGNED — [Execute/read, Share with readers only 
[ 68 | 44  |BINARY(4), UNSIGNED  [Execute/read, share with writers only = 
| 72 | 48  |BINARY(4), UNSIGNED — [Execute/read, share with readers and writers 


716 4C BINARY(4), UNSIGNED Execute/read, share with neither readers nor 
| | ce 


| 80 | 50 BINARY(4), UNSIGNED [Attribute lock 
| 84 | 54 BINARY(4), UNSIGNED | Save lock 


| 88 | 58  |BINARY(4),UNSIGNED  [internalsavelock = 
| 92 | 5C  |BINARY(4), UNSIGNED |Linkchangeslock 
[ 96 | 60  JBINARY(4),UNSIGNED  |Currentdirectory = 

100 | 64 |BINARY(4),UNSIGNED  |Rootdirectory = 

104 | 68  |BINARY(4), UNSIGNED [Fileserverreference 
[ 108 | 6C  |BINARY(4), UNSIGNED [File server working directory = 
[112 | 70 |BINARY(4), UNSIGNED |Checkedout” ss —ss—(‘“‘“‘S;CC;™; 
[ 116 { 74 |CHARGO) == ~~ (Checkedoutusername = —— 
[ 126 | 7E |CHARQ)  — |Reserved(Binary0) | 


Field Descriptions for ROROO100 and ROROO200 Output 
Structures and their Imbedded Structures 


Attribute lock. Attribute changes are prevented. 
Bytes available. Number of bytes of output data that was available to be returned. 
Bytes returned. Number of bytes returned in the output buffer. 


Checked out. Indicates whether the object is currently checked out. If it is checked out, then the Checked 
Out User Name contains the name of the user who has it checked out. 


Checked out user name. Contains the name of the user who has the object checked out, when the Checked 
Out field indicates that it is currently checked out. This field is set to blanks (x'40) if the object is not 
checked out. 


Current directory. The object is a directory that is being used as the current directory of the job. 


Displacement to extended reference types. Displacement from the beginning of the structure containing 
this field to the beginning of the Extended Reference Types structure. If this field is 0, then no extended 
reference types were available to be returned, or not enough space was provided to include any portion of 
the Extended Reference Types structure. 


Displacement to next job entry. Displacement from the beginning of the structure containing this field to 
the beginning of the next Job Using Object structure. If this field is 0, then there are no more jobs in the list, 
or not enough space was provided to include any more Job Using Object structures. 


Displacement to simple reference types. Displacement from the beginning of the structure containing this 
field to the beginning of the Simple Reference Type structure. If this field is 0, then no simple reference 
types were available to be returned, or not enough space was provided to include any portion of the Simple 
Reference Types structure. 


Execute. Execute only access. 


Execute, share with readers only. Execute only access. The sharing mode allows sharing with read and 
execute access intents only. 


Execute, share with readers and writers. Execute only access. The sharing mode allows sharing with 
read, execute, and write access intents. 


Execute, share with writers only. Execute only access. The sharing mode allows sharing with write access 


intents only. 


Execute, share with neither readers nor writers. Execute only access. The sharing mode allows sharing 
with no other access intents. 


Execute/read, share with readers only. Execute and read access. The sharing mode allows sharing with 
read and execute access intents only. 


Execute/read, share with readers and writers. Execute and read access. The sharing mode allows sharing 
with read, execute, and write access intents. 


Execute/read, share with writers only. Execute and read access. The sharing mode allows sharing with 
write access intents only. 


Execute/read, share with neither readers nor writers. Execute and read access. The sharing mode allows 
sharing with no other access intents. 


Extended reference types structure. This is a Qp0]_Ext_Ref_Types_Output structure containing fields 
that indicate different types of references that may be held on an object. Some of these are actually a 
grouping of multiple Simple Reference Types that were known to have been specified by the referring 
instance. These are not additional references; they are a redefinition of the same references described in the 
Simple Reference Types structure. 


File server reference. The File Server is holding a generic reference on the object on behalf of a client. 


File server working directory. The object is a directory, and the File Server is holding a working directory 
reference on it on behalf of a client. 


In-use indicator The object is currently in-use. NOTE: This indicator will be set to one of the following 
values: 


QPOL_OBJECT_NOT_IN_USE (0) 


The object is not in use and all of the reference type fields returned are 0. 


QPOL_OBJECT_IN_USE (1) 


The object is in use. At least one of the reference type fields is greater than 0. This condition may 
occur even if the Reference Count field's value is 0. 


Internal save lock. The object is being referenced internally during a save operation on a different object. 
Job name. Name of the job. 

Job number. Number associated with the job. 

Job user. User profile associated with the job. 


Jobs available. Number of referencing jobs available. This may be greater than the Jobs Returned field 
when the caller did not provide enough space to receive all of the job information. 


Jobs returned. Number of referencing jobs returned in the job list. 

Length of extended reference types. Length of the Extended Reference Types information. 
Length of simple reference types. Length of the Simple Reference Types information. 
Link changes lock. Changes to links in the directory are prevented. 


Offset to extended reference types. Offset from the beginning of the Receiver_Ptr to the beginning of the 


Extended Reference Types structure. If this field is 0, then no extended reference types were available to be 
returned, or not enough space was provided to include any portion of the Extended Reference Types 
structure. 


Offset to job list. Offset from the beginning of the Receiver_Ptr to the beginning of the first Job Using 
Object structure. If this field is 0, then there are no jobs in the list. 


Offset to simple reference types. Offset from the beginning of the Receiver_Ptr to the beginning of the 
Simple Reference Type structure. If this field is 0, then no simple reference types were available to be 
returned, or not enough space was provided to include any portion of the Simple Reference Types structure. 


Read only. Read only access. 


Read only, share with readers only. Read only access. The sharing mode allows sharing with read and 
execute access intents only. 


Read only, share with readers and writers. Read only access. The sharing mode allows sharing with 
read, execute, and write access intents. 


Read only, share with writers only. Read only access. The sharing mode allows sharing with write access 
intents only. 


Read only, share with neither readers nor writers. Read only access. The sharing mode allows sharing 
with no other access intents. 


Read/write. Read and write access. 


Read/write, share with readers only. Read and write access. The sharing mode allows sharing with read 
and execute access intents only. 


Read/write, share with readers and writers. Read and write access. The sharing mode allows sharing 
with read, execute, and write access intents. 


Read/write, share with writers only. Read and write access. The sharing mode allows sharing with write 
access intents only. 


Read/write, share with neither readers nor writers. Read and write access. The sharing mode allows 
sharing with no other access intents. 


Reference count. Current number of references on the object. NOTE: This may be 0 even though the 
In-Use Indicator indicates that the object is in use. 


Referencing job list. Variable length list of Qp0l_Job_Using_Object structures for jobs that are currently 
referencing the object. 


Root directory. The object is a directory that is being used as the root directory of the job. 
Save lock. The object is being referenced by an object save operation. 
Share with readers only. The sharing mode allows sharing with read and execute access intents only. 


Share with readers and writers. The sharing mode allows sharing with read, execute, and write access 
intents. 


Share with writers only. The sharing mode allows sharing with write access intents only. 


Share with neither readers nor writers. The sharing mode allows sharing with no other access intents. 


Simple reference types structure. This is a Qp0]_Sim_Ref_Types_Output structure containing fields that 
indicate different types of references that may be held on an object. 


Write only. Write only access. 


Write only, share with readers only. Write only access. The sharing mode allows sharing with read and 
execute access intents only. 


Write only, share with readers and writers. Write only access. The sharing mode allows sharing with 
read, execute, and write access intents. 


Write only, share with writers only. Write only access. The sharing mode allows sharing with write 
access intents only. 


Write only, share with neither readers nor writers. Write only access. The sharing mode allows sharing 
with no other access intents. 


Error Messages 


Message ID Error Message Text 

CPF3C21E Format name &1 is not valid. 

CPF3C24 E Length of the receiver variable is not valid. 

CPF3C36 E Number of parameters, &1, entered for this API was not valid. 
CPF3CF1 E Error code parameter not valid. 

CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFAO0D4 E File system error occurred. Error number &1. 


Usage Notes 


1. Since both available formats are variable length, following are the recommended minimum lengths 
pertaining to their corresponding formats: 


Oo ROROO100: The size of a ROROO100 Output structure plus the size of a Simple Reference 
Types structure. 


oO ROROO200: This structure varies dynamically, and therefore there is no formula that can 
yield a size large enough to always retrieve all of the available information. However, 
programs may consider first calling QPOLROR with the ROROO100 format. This will 
quickly return the number of references currently on the object. Then the program could 
allocate a buffer equal in size to: size of a Job Using Object structure (including the size of 
both the Simple and Extended Reference Type structures) multiplied by the number of 
references, and then add the sizes of a ROROO100 output, ROROO200 output, and Simple 
Reference Types structures. Now the program could call QPOLROR with the ROROO0200 
format requested and the computed size. 


If the ROROO200 format was specified, but there was not enough space provided to 


receive a complete list of job information, then only those job entries that completely fit in 
the buffer will be returned. The ROROO200 output structure contains a field called 
JobsAvailable that will always contain the total number of referencing jobs that were 
available for returning to the caller at that instance in time. 


Notes 


o There are no locks obtained on the object while this API is running. Therefore, when this 
API is used on an object that is actively in use (for example, its lock and reference state is 
changing while this API is running), some fields in the returned information may be 
inconsistent with other fields returned on the same invocation of QPOLROR. 


o The number of references on the object may change between multiple calls to this API. 
Therefore, the above formula for calculating output buffer size for a ROROO200 format 
may not be enough space under all conditions. 


o There are some reference types that are obtained on the object without incrementing the 
object's reference count. This could result in a reference count of zero while the object 
contains reference types. In this instance, the above formula for calculating output buffer 
size for a ROROO200 format may not be enough space. 


. The list of simple object reference types in the base portions of the ROROO100 and ROROO200 
output structures may not contain complete information for objects residing in file systems other 
than the Root (‘7’), QOpenSys, and User-defined file systems. The simple reference types will, 

however, be set in the job array elements in the ROROO200 output structure for any file system. 


. The list of object reference types in the ROROO200 output formats may be an incomplete list of 
references for objects residing in file systems other than the Root (‘/'), QOpenSys, and User-defined 
file systems. Objects in some of the other file systems can be locked with interfaces that do not use 
the Integrated File System. Therefore, references returned by this API will only be references that 
were obtained as part of an Integrated File System operation, or an operation that cause the 
Integrated File System operation to occur. 


. Under some circumstances, the list of jobs that are referencing the object may be incomplete. 
However, jobs not listed in the job list may still have their references listed in the ROROO100 
output. This occurs when system programs obtain references directly on an object without 
obtaining an open descriptor for the object. 


. At some instances during the save or restore of an Integrated File System object, the object may 
have references held by the job even though its reference count is 0. 


. File systems that access remote objects, such as Network File System (NFS) and the QFileSvr.400 
file systems, will only be returning references that are locally obtained on the object. Any 
references that the remote system may have on the remote object are not returned by this API. 


. This type of reference information is also viewable through the iSeries Navigator application. The 
terminology, however, differs in that iSeries Navigator refers to this type of information as "Usage" 
information instead of "Reference" information. 


Related Information 


e The <qp0lror.h> file (see Header Files for UNIX-Type Functions) 


Example 


The following is an example use of this API. 


See Code disclaimer information for information pertaining to code examples. 


#include 
#include 
#include 
#include 


<qp0lror.h> 
<stdio.h> 
<string.h> 
<stdlib.h> 


void main() 


{ 


struct PathNameStruct 


{ 


Qlg_Path_Name_T header; 


char p[50]; 


}; 


struct PathNameStruct path; 


char pathName[] = "/CustomerData"; 


Qus_EC_t errorCode; 


/* Define a constant for the number of output buffer bytes 


provided for the ROROO100 format. */ 
#define OUTPUT_BYTES_ROROO100 . 
(sizeof (Qp01_RORO0100_Output_T) + \ 
sizeof (Qp01_Sim_Ref_Types_Output_T) + \ 
100) /* Pad space for potential gap between 
the 2 structures. */ 
/* Declare some space for the ROROO100 output. if 
char output100Buf [OUTPUT_BYTES_ROROO100]; 
/* Declare a pointer for retrieving the ROROO100 format. */ 
QpO1l_ROROO100_Output_T *output100P; 
/* Declare a pointer to retrieve the ROROO200 format. * / 
QpO01l_ROROO200_Output_T *output200P; 
/* Declare a job using object pointer. x, 
Qp01l_Job_Using_Object_T *JjobP; 
unsigned outputBufSize; 
/* Set output buffer pointer and length for retrieving the 
ROROO100 format. */ 


output100P = (Qp01_RORO0100_Output_T *) output100Buf; 


/* Setup the object's path name structure. #7: 
memset (&path, 0, sizeof (path)); 

path.header.CCSID = 37; 

memcpy (path. header.Country_ID, "US",2); 

memcpy (path. header. Language_ID, "ENU", 3); 
path.header.Path_Type = QLG_CHAR_SINGLE; 
path.header.Path_Length = strlen(pathName) ; 
path.header.Path_Name_Delimiter[0] = '/'; 

memcpy (path.p, pathName, path.header.Path_Length) ; 


/* Setup the error code structure to cause the error to be 


returned within the error structure. * 
errorCode.Bytes_Provided = sizeof (errorCode) ; 
errorCode.Bytes_Available = 0; 


/* First call QPOLROR to get the short format. We will 
use that information about references to conditionally 
allocate more space and then get the longer 
running format's information. af 
QPOLROR (output100P, 
OUTPUT_BYTES_ROROO100, 
QPOLROR_ROROO100_FORMAT, 
(Qlg_Path_Name_T *) &path, 
&errorCode) ; 


/* Check if an error occurred. */ 
if (errorCode.Bytes_Available != 0) 
{ 

printf("Error occurred for ROROO100.\n"); 

return; 


} 


/* Check if we received any references that might be 
associated with a job. If not, return. */ 
if (output1l00P->Count == 0) 
{ 
printf ("QPOLROR returned a reference count of %d\n", 
output100P->Count) ; 
return; 


} 


/* If we get here, then we have at least 1 reference that 
may be identifiable to a job. We will call the 
QPOLROR API to get the ROROO200 format. First we 
compute a buffer size to use. Note: this calculation 
sums up the sizes of all structures contained within 
the ROROO200 format, but doesn't consider gaps between 


each of the structure. To attempt to cover potential 

gaps between structures, an extra 1000 bytes is being 

allocated and room for 10 additional jobs. Hifi 
outputBufSize = 


sizeof (Qp01_RORO0200_Output_T) + 
sizeof (Qp01_Sim_Ref_Types_Output_T) + 
sizeof (Qp01_Ext_Ref_Types_Output_T) + 
((output1l00P->Count + 10) * 


(sizeof (Qp01_Job_Using_Object_T) + 
sizeof (Qp01_Sim_Ref_Types_Output_T) + 
sizeof (Qp01_Ext_Ref_Types_Output_T) 

) + 1000 

); 


if (NULL == (output200P = 
(Qp01_RORO0200_Output_T *)malloc(outputBufSize) )) 
{ 

printf("No space available.\n"); 

return; 


} 


/* Retrieve object references. */ 
QPOLROR (output200P, 

outputBufSize, 

QPOLROR_ROROO0O200_FORMAT, 

(Qlg_Path_Name_T *) &path, 

&errorCode) ; 


/* Check if an error occurred. */ 
if (errorCode.Bytes_Available != 0) 
{ 

free (output200P); 

printf("Error occurred for ROROO200.\n"); 

return; 


} 


/* If there was more information available than we had 
provided receiver space for, then we will allocate a 
larger buffer and try once again. This could potentially 
keep reoccurring, but this example will stop after this 
second retry. */ 

if (output200P->BytesReturned < output200P—->BytesAvailable) 

{ 

/* Use the bytes available value to determine how much 
more buffer size is needed. We will pad it with an 
extra 1000 bytes to try and handle more jobs obtaining 
references between calls to QPOLROR. oy 

outputBufSize = output200P->BytesAvailable + 1000; 


if (NULL == (output200P = (Qp01_RORO0200_Output_T *) 
realloc((void *)output200P, 
outputBufSize) )) 


printf("No space available.\n"); 
return; 


} 


QPOLROR (output200P, 
outputBufSize, 
QPOLROR_ROROO200_FORMAT, 
(Qlg_Path_Name_T *) &path, 
&errorCode) ; 


/* Check if an error occurred. */ 
if (errorCode.Bytes_Available != 0) 


free (output200P); 
printf("Error occurred for ROROO200 (2nd call).\n"); 


return; 


} 


/* Print some output. 
printf ("Reference count: Sd\n", output200P->Count) ; 
printf ("Jobs returned: sd\n", output 200P->JobsReturned) ; 


if (output200P->JobsReturned > 0) 
{ 
jobP = (Qp01_Job_Using_Object_T *) 
((char *)output200P + output200P->JobsOffset) ; 
printf("First job's name: %10.10s %10.10s %6.6s", 
jJobP->Name, 
jobP->User, 
jobP->Number) ; 


} 


free (output200P); 


return; 
} 
Example Output: 
Reference count: 1 
Jobs returned: 1 


First job's name: JOBNAME123 JOBUSER123 123456 
< 
API introduced: V5R2 


Top | UNIX-Type APIs | APIs by category 


ad 


QpO0lSaveStgFree()--Save Storage Free 


Syntax 


#include <Qp0lstdi.h> 


int Qp0lSaveStgF ree ( 
Qlg_Path_Name_T *Path_Name, 
QpO0l_StgFree_Function_t *UserFunction_ptr, 
void *Function_CtlBlk_ptr); 


Service Program Name: QPOLLIB3 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QpO0ISaveStgFree() function calls a user-supplied exit program to save OS/400 objects of type *STMF 
and, upon successful completion of the exit program, frees the storage for the object and marks the object as 
storage freed. The *STMEF object and its attributes remain on the system, but the storage occupied by the 
*STME object's data is deleted. The *STMF object cannot be used until it is restored to the system. This is 
accomplished by either of the following: 


e Restoring the object using the RST command. 


e Requesting an operation on the object, requiring one of the following, which will dynamically 
retrieve (restore) the *STMF object: 


o Accessing the object's data (open(), creat(), MOV, CPY, CPYFRMSTMF, or 
CPYTOSTMFP). 


o Adding a new name to the object (RNM, ADDLNK, link(), rename(), 
Qp0IRenameKeep(), or Qp0IRenameUnlink(). 


o Checking out the object (CHKOUT). 


The restore operation is done by calling a user-provided exit program registered against the Storage 
Extension exit point QI]BM_QTA_STOR_EX400. For information on this exit point, see the Storage 


Extension Exit Program. 


QpO0ISaveStgFree() returns EOFFLINE for an object that is already storage freed or returns EBUSY for an 
object that is checked out. 


The user exit program can be either a procedure or a program. 


Parameters 


Path_Name 


(Input) A pointer to a path name whose last component is the object that is saved and whose storage 
is freed. This path name is in the Qlg_Path_Name_T format. For more information on this 
structure, see Path name format. 


If the last component of the path name supplied on the call to Qp0ISaveStgFree() is a symbolic 
link, then QpOISaveStgFree() resolves and follows the link to its target and performs its normal 
Qp0ISaveStgFree() functions on that target. If the symbolic link refers to an object in a remote file 
system, Qp0ISaveStgFree() returns ENOTSUP to the calling program. 


UserFunction_ptr 


(Input) A pointer to a structure that contains information about the user exit program that the caller 
wants Qp0ISaveStgFree() to call to save an *STMF object. This user exit program can be either a 

procedure or a program. If this pointer is NULL, Qp0ISaveStgFree() does not call an exit program 
to save the object but does free the object's storage and marks it as storage freed. 


User Function Pointer 


| Offset 
| Dec Hex /|Type Field 


| 0 0 BINARY(4) Function type flag 

| 14 E CHAR(10) Program library 

| 4 4 CHAR(10) Program name 

| 24 18 |CHAR() Multithreaded job action 

| 25 19 |CHAR(7) Reserved 

| 32 20 ‘|PP(*) Procedure pointer to exit procedure 


Function type flag. A flag that indicates whether the Save Storage Free exit program called by 
Qp0ISaveStgFree() is a procedure or a program. If the exit program is a procedure, this flag is set 
to 0, and the procedure pointer to exit procedure field points to the procedure called by 
Qp0lSaveStgFree(). If the exit program is a program, this flag is set to 1 and a program name and 
program library are provided, respectively, in the program name and program library fields. Valid 
values follow: 


O QPOL_USER_FUNCTION_PTR: A user procedure is called. 

I QPOL_USER_FUNCTION_PGM: A user program is called. 
Multithreaded job action. (Input) A CHAR(1) value that indicates the action to take in a 
multithreaded job. The default value is QPOL_MLTTHDACN_SYSVAL. For release compatibility 


and for processing this parameter against the QMLTTHDACN system value, x'00, x'01', x'02', & 
x'03' are treated as x'FO'" x'F1', x'F2', and x'F3'. 


x'00' QPOL_MLTTHDACN_SYSVAL: The API evaluates the QMLTTHDACN system value 
to determine the action to take in a multithreaded job. Valid QMLTTHDACN system 
values follow: 


‘Il’ Call the exit program. Do not send an informational message. 
'2' Call the exit program and send informational message CPI3C80. 


'3' The exit program is not called when the API determines that it is running in a 
multithreaded job. ENOTSAFE is returned. 


x'01' QPOL_MLTTHDACN_NOMSG: Call the exit program. Do not send an informational 
message. 


x'02' QPOL_MLTTHDACN_MSG: Call the exit program and send informational message 
CPI3C80. 


x'03' QPOL_MLTTHDACN_NO: The exit program is not called when the API determines that 
it is running in a multithreaded job. ENOTSAFE is returned. 


Procedure pointer to exit procedure. If the function type flag is 0, which indicates that a 
procedure is called instead of a program, this field contains a procedure pointer to the procedure 
that Qp0ISaveStgFree() calls. This field must be NULL if the function type flag is 1. 


Program library. If the function type flag is 1, indicating a program is called, this field contains 
the library in which the program being called (identified by the program name field) is located. 
This field must be blank if the function type flag is 0. 


Program name. If the function type flag is 1, indicating a program is called, this field contains 
the name of the program that is called. The program should be located in the library identified by 
the program library field. This field must be blank if the function type flag is 0. 


Reserved. A reserved field. This field must be set to binary zero. 
Function_CtlBlk_ptr 


(Input) A pointer to any data that the caller of Qp0ISaveStgFree() wants to have passed to the 
user-defined Save Storage Free exit program that Qp0ISaveStgFree() calls to save an *STMF 
object. Qp0ISaveStgFree() does not process the data that is referred to by this pointer. The API 
passes this pointer as a parameter to the user-defined Save Storage Free exit program that was 
specified on its call. This is a means for the caller of Qp0ISaveStgFree() to pass information to and 
from the Save Storage Free exit program. 


Authorities 


The following table shows the authorization required for the QpOISaveStgFree() API. 


Authority 
Object Referred to ae errno 


Each [Each directory, preceding the last component, ina pathname preceding [Each directory, preceding the last component, ina pathname last component, in a path name | EACCES | 
[Object =asne *SAVSYS or *RW ae 
[Any called program pointed to by the UserFunction_ptr parameter [Any called program pointed to by the UserFunction_ptr parameter program pointed to by the UserFunction_ptr parameter [9 *X | EACCES — 


Any library containing the called program pointed to by the 4 
UserFunction_ptr parameter 


Return Value 


O Qp0lSaveStgFree() was successful. 


-1 Qp0lSaveStgFree() was not successful. The errno global variable is set to indicate the error. 


Error Conditions 


If QpO0ISaveStgFree() is not successful, errno indicates one of the following errors: 
[EACCES] 


Permission denied. 
An attempt was made to access an object in a way forbidden by its object access permissions. 
The thread does not have access to the specified file, directory, component, or path. 


If you are accessing a remote file through the Network File System, update operations to file 
permissions at the server are not reflected at the client until updates to data that is stored locally by 
the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) 
command determine the time between refresh operations of local data.) Access to a remote file may 
also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote 
systems. 


[EAGAIN] 


Operation would have caused the process to be suspended. 


[EBADNAME] 


The object name specified is not correct. 


[EBUSY] 


Resource busy. 


An attempt was made to use a system resource that is not available at this time. 
[EDAMAGE] 


A damaged object was encountered. 


A referenced object is damaged. The object cannot be used. 
[EFAULT] 


The address used for an argument is not correct. 
In attempting to use an argument in a call, the system detected an address that is not valid. 


While attempting to access a parameter passed to this function, the system detected an address that 
is not valid. 


[EINVAL] 


The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on an object and 
the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. 
[EIO] 


Input/output error. 
A physical I/O error occurred. 


A referenced object may be damaged. 


[EISDIR] 


Specified target is a directory. 
The path specified named a directory where a file or object name was expected. 


The path name given is a directory. 
[ELOOP] 
A loop exists in the symbolic links. 
This error is issued if the number of symbolic links encountered is more than POSIX_S YMLOOP 


(defined in the limits.h header file). Symbolic links are encountered during resolution of the 
directory or path name. 


[EMFILE] 
Too many open files for this process. 
An attempt was made to open more files than allowed by the value of OPEN_MAX. The value of 
OPEN_MAX can be retrieved using the sysconf() function. 
The process has more than OPEN_MAX descriptors already open (see the sysconf() function). 
[ENAMETOOLONG] 
A path name is too long. 
A path name is longer than PATH_MAX characters or some component of the name is longer than 
NAME_MAX characters while _POSIX_NO_TRUNC is in effect. For symbolic links, the length 


of the name string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and 
NAME_MAxX values can be determined using the pathconf() function. 


[ENFILE] 


Too many open files in the system. 


A system limit has been reached for the number of files that are allowed to be concurrently open in 
the system. 


The entire system has too many other file descriptors already open. 
[ENOENT] 
No such path or directory. 


The directory or a component of the path name specified does not exist. 


A named file or directory does not exist or is an empty string. 
[ENOMEM] 


Storage allocation request failed. 
A function needed to allocate storage, but no storage is available. 


There is not enough memory to perform the requested function. 
[ENOTDIR] 


Not a directory. 


A component of the specified path name existed, but it was not a directory when a directory was 
expected. 


Some component of the path name is not a directory, or is an empty string. 


[ENOSPC] 


No space available. 


The requested operations required additional space on the device and there is no space left. This 
could also be caused by exceeding the user profile storage limit when creating or transferring 
ownership of an object. 


Insufficient space remains to hold the intended file, directory, or link. 
[ENOSYSRSC] 


System resources not available to complete request. 


[ENOTSAFE] 


Function is not allowed in a job that is running with multiple threads. 
[ENOTSUP] 
Operation not supported. 


The operation, though supported in general, is not supported for the requested object or the 
requested arguments. 


[EOFFLINE] 
Object is suspended. 


You have attempted to use an object that has had its data saved and the storage associated with it 
freed. An attempt to retrieve the object's data failed. The object's data cannot be used until it is 
successfully restored. The object's data was saved and freed either by saving the object with the 
STG(*FREE) parameter, or by calling an API. 


[EUNKNOWN] 


Unknown system state. 


The operation failed because of an unknown system state. See any messages in the job log and 
correct any errors that are indicated, then retry the operation. 


Error Messages 


The following messages may be sent from this function: 
Message ID Error Message Text 
CPI3C80 I An exit program has been called for which the threadsafety status was not known. 
CPFAOD4 E _ File system error occurred. 
CPE3418 E Possible APAR condition or hardware failure. 
CPF3CF2E — Error(s) occurred during running of &1 API. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 


e This function will fail with error code [ENOTSAFE] when both of the following conditions occur: 
oO Where multiple threads exist in the job. 


o The object this function is operating on resides in a file system that is not threadsafe. Only 
the following file systems are threadsafe for this function: 


= Root 

m QOpenSys 
m User-defined 
wg QNTC 

gw QSYS.LIB 
gw QOPT 


e If the Save Storage Free exit program calls the SAV command or the QsrSave function or any 
other function that is not threadsafe, and there are secondary threads active in the job, 
QpOlSaveStgFree() may fail as a result. 


e If the Save Storage Free exit program is not threadsafe or uses a function that is not threadsafe, then 
Qp0lISaveStgFree() is not threadsafe. 


Related Information 
e The <Qp0lstdi.h> file 


e@ OlgSaveStgFree()--Save Storage Free (using NLS-enabled path name) 


e Save Storage Free Exit Program 


Example 


See Qp0lGetAttr() description for a code example that shows a call to Qp0ISaveStgFree() by using a 
procedure as the exit program. This API also shows an example of a call to Qp01GetAttr(). 


API introduced: V4R3 


Top | Backup and Recovery APIs | UNIX-Type APIs | APIs by category 


QpOlSetAttr()--Set Attributes 


Syntax 


#include <Qp0lstdi.h> 

int Qp0lSetAttr 
(Qlg_Path_Name_T *Path_Name, 
char *Buffer_ptr, 
uint Buffer_Size, 
uint Follow_Symlink, 


Service Program Name: QPOLLIB3 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The QpOISetAttr() function sets one of a set of defined attributes, on each call, for the object that is 
referred to by the input *Path_Name. The object must exist, the user must have authority to it, and the 
attribute must be supported by the file system to which the object belongs. When an attribute is not 
supported by the file system, QpO0ISetAttr() will fail with ENOTSUP. See the Usage Notes section for 
more information. 


If the last component of the Path_Name parameter is a symbolic link, the QpO0ISetAttr() either sets the 
attribute of the symbolic link or sets the attribute of the object that the symbolic link names. This depends 
on the value of the Follow_Symink parameter. 


All times that are set by Qp0ISetAttr() are in seconds since the Epoch so that they are consistent with 
UNIX-type APIs. The Epoch is the time 0 hours, 0 minutes, 0 seconds, January 1, 1970, Coordinated 
Universal Time. If the OS/400 date is set prior to 1970, all time values will be zero. 


Parameters 


Path_Name 


(Input) The path name of the object for which attribute information is set. This path name is in the 
Qlg_ Path_Name_T format. For more information on this structure, see Path name format. 


Buffer_ptr 


(Input) A pointer to a buffer containing a constant that identifies the attribute and the value for the 
attribute that Qp0ISetAttr(Q) sets. The number of bytes allocated for this buffer is in the Buffer_Size 
parameter. 


The following table describes the format of the entry in the buffer. 


[Bu iffer Pointer 


| Offset 
[Dec [Hex |Type Field 


| 0 | 0 [BINARY (4) [Offset to next attribute entry 


[4 [4 |[BINARYG@) ___[Attributeidentification = ss—~S~S 
[8 | 8 [BINARYG) — [Size of attribute data 
[12 [C |CHAR@——=i«diReseved—Sss—=—“—*~*~*~*~s~S~—S 


Attribute data. The value to which the attribute is set. 


Attribute identification. The constant identifying the attribute being set. Valid values are: 


4 


17 


18 


19 


20 


QPOL_ATTR_CREATE_TIME: (UNSIGNED (BINARY(4)) The time the object was 
created. 


QPOL_ATTR_ACCESS_TIME: (UNSIGNED (BINARY(4)) The time the object's data 
was last accessed. 


QPOL_ATTR_MODIFY_TIME: (UNSIGNED (BINARY(4)) The time the object's data 
was last changed. 


QPOL_ATTR_PC_READ_ONLY: (CHAR(1)) Whether the object can be written to or 
deleted, have its extended attributes changed or deleted, or have its size changed. Valid 
values are: 


x'00' QPOL_PC_NOT_READONLY: The object can be changed. 
x'01' QPOL_PC_READONLY: The object cannot be changed. 


QPOL_ATTR_PC_HIDDEN: (CHAR(1)) Whether the object can be displayed using an 
ordinary directory listing. 


x'00' QPOL_PC_NOT_HIDDEN: The object is not hidden. 
x'Ol' QPOL_PC_HIDDEN: The object is hidden. 


QPOL_ATTR_PC_SYSTEM: (CHAR(1)) Whether the object is a system file and is 
excluded from normal directory searches. 


x'00' QPOL_PC_NOT_SYSTEM: The object is not a system file. 
x'01' QPOL_PC_SYSTEM: The object is a system file. 


QPOL_ATTR_PC_ARCHIVE: (CHAR(1)) Whether the object has changed since the 
last time the file was saved or reset by a PC client. 


x'00' QPOL_PC_NOT_CHANGED: The object has not changed. 
x'Ol' QPOL_PC_CHANGED: The object has changed. 


21 


22 


26 


27 


31 


QPOL_ATTR_SYSTEM_ARCHIVE: (CHAR(1)) Whether the object has changed and 
needs to be saved. It is set on when an object's change time is updated, and set off when 
the object has been saved. 


x'00' QPOL_SYSTEM_NOT_CHANGED: The object has not changed and does not 
need to be saved. 


x'01' QPOL_SYSTEM_CHANGED: The object has changed and does need to be 
saved. 


QPOL_ATTR_CODEPAGE: (BINARY(4)) The code page used to derive a coded 
character set identifier (CCSID) used for the data in the file or the extended attributes of 
the directory. 


QPOL_ATTR_ALWCKPWRT: (CHAR(1)) Whether a stream file (*STMF) can be 
shared with readers and writers during the save-while-active checkpoint processing. 
Setting this attribute may cause unexpected results. Please refer to the Backup and 


ee ee for details on this attribute. 


x'00' QPOL_NOT_ALWCKPWRT: The object can be shared with readers only. 


x'0l'’ QPOL_ALWCKPWRT: The object can be shared with readers and writers. 


QPOL_ATTR_CCSID: (BINARY(4)) The CCSID of the data and extended attributes of 
the object. 


QPOL_ATTR_DISK_STG_OPT (CHAR(1)) Which option should be used to determine 
how auxiliary storage is allocated by the system for the specified object. The option will 
take effect immediately and be part of the next auxiliary storage allocation for the 
object. This option can only be specified for byte stream files in the Root (/), QOpensys 
and User-defined file systems. This option will be ignored for *TYPE1 byte stream files. 
Valid values are: 


x'00' QPOL_STG_NORMAL: The auxiliary storage will be allocated normally. 
That is, as additional auxiliary storage is required, it will be allocated in 
logically sized extents to accomodate the current space requirement, and 
anticipated future requirements, while minimizing the number of disk I/O 
operations. If the QPOL_ATTR_DISK_STG_OPT attribute has not been 
specified for an object, this value is the default. 


x'0O1' QPOL_STG_MINIMIZE: The auxiliary storage will be allocated to minimize 
the space used by the object. That is, as additional auxiliary storage is 
required, it will be allocated in small sized extents to accomodate the current 
space requirement. Accessing an object composed of many small extents may 
increase the number of disk I/O operations for that object. 


x'02' QPOL_STG_DYNAMIC: The system will dynamically determine the 
optimum auxiliary storage allocation for the object, balancing space used 
versus disk I/O operations. For example, if a file has many small extents, yet is 
frequently being read and written, then future auxiliary storage allocations will 
be larger extents to minimize the number of disk I/O operations. Or, if a file is 
frequently truncated, then future auxiliary storage allocations will be small 
extents to minimize the space used. Additionally, information will be 
maintained on the byte stream file sizes for this system and its activity. This 
file size information will also be used to help determine the optimum auxiliary 
storage allocations for this object as it relates to the other objects sizes. 


32 
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300 


QPOL_ATTR_MAIN_STG_OPT: (CHAR(1)) Which option should be used to 
determine how main storage is allocated and used by the system for the specified object. 
The option will take effect the next time the specified object is opened. This option can 
only be specified for byte stream files in the Root (/), QOpensys and User-defined file 
systems. Valid values are: 


x'00' QPOL_STG_NORMAL: The main storage will be allocated normally. That is, 
as much main storage as possible will be allocated and used. This minimizes 
the number of disk I/O operations since the information is cached in main 
storage. If the QPOL_ATTR_MAIN_STG_OPT attribute has not been 
specified for an object, this value is the default. 


x'Ol' QPOL_STG_MINIMIZE: The main storage will be allocated to minimize the 
space used by the object. That is, as little main storage as possible will be 
allocated and used. This minimizes main storage usage while increasing the 
number of disk I/O operations since less information is cached in main 
storage. 


x'02' QPOL_STG_DYNAMIC: The system will dynamically determine the 
optimum main storage allocation for the object depending on other system 
activity and main storage contention. That is, when there is little main storage 
contention, as much storage as possible will be allocated and used to minimize 
the number of disk I/O operations. And when there is significant main storage 
contention, less main storage will be allocated and used to minimize the main 
storage contention.*& 


QPOL_ATTR_RESET_DATE: (UNSIGNED (BINARY (2)) The count of the number of 
days an object has been used. Usage has different meanings according to the file system 
and according to the individual object types supported within a file system. Usage can 
indicate the opening or closing of a file or can refer to adding links, renaming, restoring, 
or checking out an object. The usage information format is defined in the QpOlIstdi.h 
header file as data type Qp01_Usage_t and is shown in the following table. This attribute 
can be set to zero only. An attempt to set to any other value will result in errno 
[EINVAL]. 


When this attribute is set, the date use count reset for the object is set to the current date. 


QPOL_ATTR_SUID: (CHAR(1)) Set effective user ID (UID) at execution time. This 
value is ignored if the specified object is a directory. Valid values are: 


x'00' QPOL_SUID_OFF: The user ID (UID) is not set at execution time. 


x'O1l' QPOL_SUID_ON: The object owner is the effective user ID (UID) at 
execution time. 


301 QPOL_ATTR_SGID: (CHAR(1)) Set effective group ID (GID) at execution time. Valid 
values are: 


x'00' QPOL_SGID_OFF: If the object is a file, the group ID (GID) is not set at 
execution time. If the object is a directory in the Root (‘/'), QOpensys, and 
user-defined file systems, the group ID (GID) of objects created in the 
directory is set to the effective GID of the thread creating the object. This 
value cannot be set for other file systems. 


x'01' QPOL_SGID_ON: If the object is a file, the group ID (GID) is set at execution 
time. If the object is a directory, the group ID (GID) of objects created in the 
directory is set to the GID of the parent directory.*& 


Offset to next attribute entry. (Output) This field is not used by the QpO0ISetAttr() function. It is 
provided for alignment so that the same buffer format returned from the Qp0IGetAttr() function 
can be used as input to the QpOISetAttr() function. 


Reserved. A reserved field. This field must be set to binary zero. 


Size of attribute data. The exact size of the data for this attribute. If this size does not match the 
size that the system stores for this attribute, [EINVAL] is returned. 


Buffer_Size 
(Input) The size in bytes of the buffer pointed to by the Buffer_ptr parameter. 
Follow_Symlnk 
(Input) If the last component in the *Path_Name is a symbolic link, Qp0ISetAttr() either acts upon 


the symbolic link or the path contained in the symbolic link. This depends on the value of the 
Follow_Symlnk parameter. Valid values are: 


0 QPOL_DONOT_FOLLOW_SYMLNK: A symbolic link in the last component is not 
followed. Attributes of the symbolic link object are set. 


I QPOL_FOLLOW_SYMLNK: A symbolic link in the last component is followed. The 
attributes of the object contained in the symbolic link are set. 


Authorities 


Note: Adopted authority is not used. 


Authorization Required for Qp0ISetAttr() (excluding OSYS.LIB and independent ASP QSYS.LIB)*& 


Authority 
Object Referred to Required errno 


[Each directory, preceding the last component, in the path name *x EACCES 


Object, when setting the QPOL_ATTR_DAYS_USED_COUNT, | |*OBJMGT EACCES 
= QPOL_ATTR_ALWCKPWRT, QPOL_ATTR_DIST_STG_OPT 

or QPOL_ATTR_MAIN_STG_OPT “attribute 

Object, when setting the QPOL_ATTR_CREATE_TIME, Owner or *W (See |EACCES 


QPOL_ATTR_ACCESS_TIME, or Note) 
QPOL_ATTR_MODIFY_TIME attribute to the current time 


2 Object, when setting the QPOL_ATTR_SUID or Owner (See Note) |EACCES*&% 
QPOlATTR_SGID values 


Object, when setting the QPOL_ATTR_CREATE_TIME, *W EPERM 
QPOL_ATTR_ACCESS_TIME, or 

QPOL_ATTR_MODIFY_TIME attribute to a specific time 

(Object, when setting any other attribute [Wo EACCES 


Note: If the file system supports *ALLOBJ special authority and if you rer *ALLOBJ eS authority, 


you do not need the listed object authority. 


Authorization Required for Op0ISetAttr() (OSYS.LIB #*and independent ASP OSYS.LIB)®&. 


Authority 
Object Referred to — errno 


[Each directory, preceding the last component, in the pathname [Each directory, preceding the last component, in the pathname preceding the last component, in the path name [*xX = JEACCES 


Object, when setting the QPOL_ATTR_DAYS_USED_COUNT Sr — and a 
attribute and the object type is *FILE *OBJMGT 


Object, when setting the QPOL_ATTR_DAYS_USED_COUNT *X and *OBJMGT |EACCES 
attribute and the object is a database file member 

Object, when setting the QPOL_ATTR_DAYS_USED_COUNT *OBJMGT EACCES 
attribute and the object is neither a *FILE object type nor a 

database file member 


Return Value 


O The QpOlISetAttr() API was successful. 


-1 The QpOlSetAttr(Q) API was not successful. The errno global variable is set to indicate the error. 


Error Conditions 


If the QpOISetAttr(Q) API is not successful, errno indicates one of the following errors: 
[EACCES] 


Permission denied. 
An attempt was made to access an object in a way forbidden by its object access permissions. 
The thread does not have access to the specified file, directory, component, or path. 


If you are accessing a remote file through the Network File System, update operations to file 
permissions at the server are not reflected at the client until updates to data that is stored locally by 
the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) 
command determine the time between refresh operations of local data.) Access to a remote file may 
also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote 
systems. 


[EAGAIN] 


Operation would have caused the process to be suspended. 


[EBADFID] 


A file ID could not be assigned when linking an object to a directory. 
The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as possible. 
[EBADNAME] 


The object name specified is not correct. 


[EBUSY] 


Resource busy. 


An attempt was made to use a system resource that is not available at this time. 
[ECANCEL] 


Operation canceled. 


[ECONVERT] 


Conversion error. 


One or more characters could not be converted from the source CCSID to the target CCSID. 
[EDAMAGE] 


A damaged object was encountered. 


A referenced object is damaged. The object cannot be used. 
[EFAULT] 


The address used for an argument is not correct. 
In attempting to use an argument in a call, the system detected an address that is not valid. 


While attempting to access a parameter passed to this function, the system detected an address that 
is not valid. 


[EINTR] 


Interrupted function call. 
[EINVAL] 
The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on an object and 
the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. 
[EIO] 


Input/output error. 


A physical I/O error occurred. 


A referenced object may be damaged. 
[EJRNDAMAGE] 
Journal damaged. 
A journal or all of the journal's attached journal receivers are damaged, or the journal sequence 


number has exceeded the maximum value allowed. This error occurs during operations that were 
attempting to send an entry to the journal. 


[EJRNENTTOOLONG] 
Entry too large to send. 


The journal entry generated by this operation is too large to send to the journal. 
[EJRNINACTIVE] 

Journal inactive. 

The journaling state for the journal is *INACTIVE. This error occurs during operations that were 

attempting to send an entry to the journal. 
[EJRNRCVSPC] 

Journal space or system storage error. 

The attached journal receiver does not have space for the entry because the storage limit has been 


exceeded for the system, the object, the user profile, or the group profile. This error occurs during 
operations that were attempting to send an entry to the journal. 


[ELOOP] 
A loop exists in the symbolic links. 
This error is issued if the number of symbolic links encountered is more than POSIX_SYMLOOP 


(defined in the limits.h header file). Symbolic links are encountered during resolution of the 
directory or path name. 


[ENAMETOOLONG] 
A path name is too long. 
A path name is longer than PATH_MAX characters or some component of the name is longer than 
NAME_MAX characters while _POSIX_NO_TRUNC is in effect. For symbolic links, the length 


of the name string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and 
NAME_MAxX values can be determined using the pathconf() function. 


[ENEWJRN] 
New journal is needed. 
The journal was not completely created, or an attempt to delete it did not complete successfully. 


This error occurs during operations that were attempting to start or end journaling, or were 
attempting to send an entry to the journal. 


[ENEWJRNRCV] 
New journal receiver is needed. 


A new journal receiver must be attached to the journal before entries can be journaled. This error 
occurs during operations that were attempting to send an entry to the journal. 


[ENOENT] 
No such path or directory. 


The directory or a component of the path name specified does not exist. 


A named file or directory does not exist or is an empty string. 
[ENOMEM] 


Storage allocation request failed. 
A function needed to allocate storage, but no storage is available. 


There is not enough memory to perform the requested function. 
[ENOSPC] 
No space available. 
The requested operations required additional space on the device and there is no space left. This 
could also be caused by exceeding the user profile storage limit when creating or transferring 
ownership of an object. 
Insufficient space remains to hold the intended file, directory, or link. 
[ENOTAVAIL] 
Independent auxiliary storage pool (ASP) is not available. 
The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage (RCLSTG) 
processing. 
To recover from this error, wait until processing has completed for the independent ASP. 
[ENOTDIR] 
Not a directory. 
A component of the specified path name existed, but it was not a directory when a directory was 
expected. 
Some component of the path name is not a directory, or is an empty string. 
[ENOTSAFE] 


Function is not allowed in a job that is running with multiple threads. 


[ENOTSUP] 
Operation not supported. 
The operation, though supported in general, is not supported for the requested object or the 
requested arguments. 

[EOFFLINE] 
Object is suspended. 
You have attempted to use an object that has had its data saved and the storage associated with it 
freed. An attempt to retrieve the object's data failed. The object's data cannot be used until it is 


successfully restored. The object's data was saved and freed either by saving the object with the 
STG(*FREE) parameter, or by calling an API. 


[EPERM] 
Operation not permitted. 
You must have appropriate privileges or be the owner of the object or other resource to do the 
requested operation. 

[EROOBJ] 


Object is read only. 


You have attempted to update an object that can be read only. 
[EUNKNOWN] 


Unknown system state. 


The operation failed because of an unknown system state. See any messages in the job log and 
correct any errors that are indicated, then retry the operation. 


If interaction with a file server is required to access the object, errno could also indicate one of the 
following errors: 


[EADDRNOTAVAIL] 


Address not available. 


[ECONNABORTED] 


Connection ended abnormally. 


[ECONNREFUSED] 


The destination socket refused an attempted connect operation. 


[ECONNRESET] 


A connection with a remote socket was reset by that socket. 


[EHOSTDOWN] 


A remote host is not available. 


[EHOSTUNREACH] 


A route to the remote host is not available. 


[ENETDOWN] 


The network is not currently available. 


[ENETRESET] 


A socket is connected to a host that is no longer available. 


[ENETUNREACH] 


Cannot reach the destination network. 


[ESTALE] 


File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may have been deleted 
at the server. 
[ETIMEDOUT] 


A remote host did not respond within the timeout period. 


[EUNATCH] 


The protocol required to support the specified address family is not available at this time. 


Error Messages 


The following messages may be sent from this function: 
Message ID Error Message Text 
CPFA0D4 E File system error occurred. Error number &1. 
CPF3CF2 E Error(s) occurred during running of &1 API. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPE3418 E Possible APAR condition or hardware failure. 


Usage Notes 


1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 
oO Where multiple threads exist in the job. 


oO The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


m Root 

m QOpenSys 

m User-defined 

gw QNTC 

mw QSYS.LIB 

m = Independent ASP QSYS.LIB & 
gw QOPT 


2. Root, QOpenSys, and User-Defined File System Differences 


The QPOL_ATTR_CREATE_TIME and QPOL_ATTR_DAYS_USED_COUNT attributes are 
supported for objects of type *STMEF only. Attempts to set them on other objects will result in the 
operation failing with errno set to [ENOTSUP]. 


3. QSYS.LIB #and Independent ASP QSYS.LIB *&File System Differences 


The following attribute may be set on objects in these file system: 
oO QPOL_ATTR_DAYS_USED_COUNT 


Attempting to set any other attribute will result in the operation failing with errno set to 


[ENOTSUP]. 


When you set the QPOL_ATTR_DAYS_USED_COUNT attribute of a database file, all members 
in that file will have their days used count reset to 0 also. 


4. Network File System Differences 
When you set the following attributes on objects in the Network File System, the operation will fail 
with the errno set to [ENOTSUP] if the attribute is not set to the following attribute value. 


o If set, QPOL_ATTR_PC_READ_ONLY must be set to an attribute value of 
QPOL_PC_NOT_READ_ONLY. 


o If set, QPOL_ATTR_PC_HIDDEN must be set to an attribute value of 
QPOL_PC_NOT_HIDDEN. 


o If set, QPOL_ATTR_PC_SYSTEM must be set to an attribute value of 
QPOL_PC_NOT_SYSTEM. 


o If set, QPOL_ATTR_PC_ARCHIVE must be set to an attribute value of 
QPOL_PC_NOT_CHANGED; however, if the object is of type *STMF, the attribute value 
must be QPOL_PC_CHANGED. 


o If set, QPOL_ATTR_ SYSTEM ARCHIVE must be set to an attribute value of 
QPOL_SYSTEM_NOT_CHANGED. 


The QPOL_ATTR_CREATE_TIME, QPOL_ATTR_DAYS_USED_COUNT, 
QPOL_ATTR_CODEPAGE, and QPOL_ATTR_CCSID attributes cannot be set on objects within 
the Network File System or they will result in the operation failing with errno set to [ENOTSUP]. 


5. QNetWare File System Differences 


The QNetWare File System does not support setting QPOL_ATTR_SYSTEM_ARCHIVE or 
QPOL_ATTR_DAYS_USED_COUNT. If you set any attribute on a NetWare Directory Services 
(NDS) object, the operation will fail with errno set to [ENOTSUP]. 


Related Information 


e The <QpOlstdi.h> file (see Header Files for UNIX-Type Functions) 


e The <qlg.h> file (see Header Files for UNIX-Type Functions) 
e =chmod()--Change File Authorizations*& 
e@ OlgSetAttrQ--Set Attributes (using NLS-enabled path name) 


e@ Qp01GetAttr()--Get Attributes*® 


Example 


The following is an example showing a call to the QpOISetAttr() and the Qp0IlGetAttrQ APIs. 


See Code disclaimer information for information pertaining to code examples. 


[BR KKK KKK RK KK KK KK EE I I KK KK KK KKK / 


#include "QpOlstdi.h" 
#include <stdio.h> 
#include <errno.h> 
#include <stdlib.h> 
#include <sys/types.h> 


int GetAttrObject ( 
Qlg_Path_Name_T *Pathname_ptr, 
char *Buffer_ptr, 
unsigned int Buffer_size) 


{ 


[RK KK KK KK KK KK KK EK I KK KK KKK / 


/* Local variables * / 
[BRK KK KR KK KK KK KK RK I RK KK KKK / 
struct attrstruct 
{ 
Qp0Ol_AttrTypes_List_t attr_struct; 
uint AttrTypes[10]; 
}; 
struct attrStruct Attr_types_ptr; 


unsigned int buff_size_needed; 
unsigned int num_bytes_returned; 
unsigned int follow_sym; 

int rc; 


[RK KK KK KK KK KK KR EE RK KR KK KK KK / 


/* Start of executable code a A 
[BRK KKK KKK KK KK KR KK RK KK KK / 


[RK KKK KKK KK KK KK KE RK IE RK KK KK / 


/* Initialize Get Attributes Parameters tf 
[BRK KK KK RK KK KK RK I KR KK KK KK / 
memset ((void *) &Attr_types_ptr, 0x00,sizeof(struct attrStruct)); 
Attr_types_ptr.attr_struct.Number_Of_RegAttrs = 3; 
Attr_types_ptr.AttrTypes[0] = QPOL_ATTR_PC_READ_ONLY; 
Attr_types_ptr.AttrTypes[1] = QPOL_ATTR_PC_HIDDEN; 
Attr_types_ptr.AttrTypes [2] QPOL_ATTR_CODEPAGE; 
buff_size_ needed = 0; 
follow_sym = QPOL_FOLLOW_SYMLNK; 


[BRK KK KK RK KK KK KR KK I KK KK KKK / 


/* Call Qp0lGetAttr() to retrieve attributes. */ 
[RK KK KK KK KK KK KK EE IE I RK KK KK / 
re = Qp0lGetAttr(Pathname_ptr, 

(Qp01_AttrTypes_List_t *)&Attr_types_ptr, 

Buffer_ptr, 

Buffer_size, 


é&buff_size_ needed, 
&énum_bytes_returned, 
follow_sym) ; 


if((rce == 0) && /* I£ successful, but */ 
(num_bytes_returned <= 0)) /* Incorrect bytes returned */ 
rc = EUNKNOWN; /* Unknown error */ 


return(rc); 
} /* End GetAttrObject () ay 


int SetAttrObject ( 
Qlg_Path_Name_T *Pathname_ptr, 
char *Buffer_ptr, 
unsigned int Buffer_size) 


[BRK KKK RK KK KK KE I I I I I KK KK KK / 


/* Local variables */ 
[BRK KKK RK KK KK KI KI I I I KK KK / 


unsigned int follow_sym; 
int ee 

int done = 0; 
unsigned int attrSize; 


QpOl_Attr_Header_t *attrPtr; 


[RK KKK RK KK KK KK I KK KK KKK / 


/* Start of executable code ai 
[RK KKK RK KK KK KI KK I KK KKK / 


[BRK KKK RK KK KR KK I KK KKK / 


/* Initialize Set Attributes Parameters a 
[BRK KKK KK KK KK KK I IE I I KK KK / 


follow_sym = QPOL_FOLLOW_SYMLNK; 


[RK KKK RK KK KK KK I I I RK KK KK / 


/* QpOlSetAttr() only sets one attribute at a time. The * 
/* buffer from Qp0l1GetAttr may contain more than one #7. 
/* attribute to set. We may have to call Qp0lSetAttr() ia A 
/* multiple times. The Next_Attr_Offset value is the key. bas 
/* If it is greater than zero, then there is another */ 
/* attribute in the buffer. Also, it is important to note */ 
/* that the value stored there is the offset from the start */ 
/* of the buffer, not the offset from the start of the */ 
/* current entry. */ 


[RK KKK KK KR KK KI I I RK KK KK / 
attrPtr = (Qp0l_Attr_Header_t *)Buffer_ptr; 
while (!done) 


{ 
attrSize = attrPtr->Attr_Size + 


sizeof (Qp01_Attr_Header_t); /* Calculate attr size */ 
[RK KK KK KK KK KK KK I I I I KK KK / 
/* Call QpOlSetAttr() to set the attribute */ 


[RK KK KK KR KK KK KI I I I I KK KK / 
rc=Qp01SetAttr(Pathname_ptr, 


(char *)attrPtr, 
attrSize, 
follow_sym) ; 


if(rce != 0) /* If the function failed #7. 
done = 1; /* End the loop */ 
else if (attrPtr->Next_Attr Offset > 0) /* If more data ase 
attrPtr = (Qp0l_Attr_Header_t *) /* Set attribute m/f 
(Buffer_ptr + attrPtr->Next_Attr_Offset); /* pointer */ 
else /* No more data aA 
done = 1; /* End the loop */ 
} 

return(rc); 

/* End SetAttrObject () R/, 


int main (int argc, char *argv[]) 
"FRED" 


"FRED2" 


#define MYPN 
#define MYPN2 


[RK KKK KK KR KK I I KI KK KK KK / 


/* Local variables 


xf 


[RK KKK RK KK KK KI I I EK RK KK KKK / 


const char US_const[3] = "US"; 
const char Language_const[4] = 


const char Path_Name_Del_const[2] = 


typedef struct pnstruct 
{ 
Qlg_Path_Name_T 
char 


He 2 


gqlg_struct; 
pn[sizeof (MYPN) ]; 


typedef struct pnstruct2 
{ 
Qlg_Path_Name_T 
char 


} | 


gqlg_struct; 


struct pnstruct pns; 
struct pnstruct2 pns2; 
int rc; 


char BufferArea[250]; 


unsigned int buffer_size = 250; 


pn[sizeof (MYPN2) ]; 


"RNU Ww 7 


ae 


[RK KKK KK KK KK KR I I I RK I KK KK / 


/* Start of executable code 


ae 


[RK KKK KK KK KK KR KK KI RK KK KKK / 


[BRK KKK KK KK KK KE I I I KK KK KK / 


/* Initialize Pathname for original object 


ae 


[RK KKK KK KK KK KK I I IE IK KK KK / 


memset ((void *)&pns, 0, 


pns.qlg_struct.CCSID = 37; 


sizeof (struct pnstruct)); 


memcpy (pns.qlg_struct.Country_ID,US_const,2); 
memcpy (pns.qlg_struct.Language_ID, Language_const, 3) ;; 


pns.qlg_struct.Path_Type = 0; 


pns.qlg_struct.Path_Length = sizeof(MYPN) - 1; 
memcpy (pns.qlg_struct.Path_Name_Delimiter, Path_Name_Del_const,1)j; 
memcpy (pns.pn,MYPN, sizeof (MYPN) ); 


[RK KK KK KK KK KK KK RK KK KKK / 


/* Call GetAttrObject to retrieve attributes from the source */ 
/* Cbjeet. ats 
[RK KKK KKK KK KK KK I I RK KK KKK / 
re = GetAttrObject ((Qlg_Path_Name_T *) &pns, 

BufferArea, 

buffer_size); 
if (re == 0) /* If GetAttr succeeded */ 
{ 


[RK KK KK RK KK KR KK RK I I EK KK / 


/* Initialize Pathname for target object ard 

[BRK KKK KR RK KK KK KK KK I I KR RK KK / 
memset ((void *)&pns2, 0, sizeof(struct pnstruct2)); 
pns2.qlg_struct.CCSID = 37; 

memcpy (pns2.qlg_struct.Country_ID,US_const,2); 

memcpy (pns2.qlg_struct.Language_ID, Language_const,3);; 
pns2.qlg_struct.Path_Type = 0; 

pns2.qlg_struct.Path_Length = sizeof (MYPN2)-1; 

memcpy (pns2.qlg_struct.Path_Name_Delimiter, Path_Name_Del_const,1); 
memcpy (pns2.pn,MYPN2, sizeof (MYPN2) ); 


[RK KK KK KK KK KK KK KE I EE RK KK / 


/* Call SetAttrObject to set attributes on the target i, 
/* ebgject. wy 
[BORK KKK RK KK KK KR RK KK KK RK KK / 
re=SetAttrobject ((Qlg_Path_Name_T *) &pns2, 

BufferArea, 

buffer_size); 


re = errno; /* return errno from SetAttrObject */ 
printf ("Qp0lSetAttr() for %s failed with %i.\n",pns2.pn,rc) ; 
} 


} /* end check GetAttrObject re */ 
else /* GetAttrObject failed * / 
{ 

re = errno; /* return errno from GetAttrObject */ 


printf ("Qp01lGetAttr() for %s failed with %s.\n",pns.pn,rc); 
} 


return(rc); 
} /* end main * / 


API introduced: V4R4 


Top | UNIX-Type APIs | APIs by category 


Qp0IUnlink()--Remove Link to File 


Syntax 


#include <Qp0lstdi.h> 


int Qp01Unlink (Qlg_Path_Name_T *Path_Name) ; 


Service Program Name: QPOLLIB1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes on open() API. 


The Qp0IUnlink() function, similar to the unlink() function, removes a directory entry that refers to a file. 
QpOlUnlinkQdiffers from unlink() in that the Path_Name parameter is a pointer to a Qlg_Path_Name_T 
structure instead of a pointer to a character string. 


For a discussion of the authorities required, return values, and related information, see unlink(Q)--Remove 
Link to File. 


Parameters 


Path_Name 


(Input) The path name of the object to be unlinked. This path name is in the Qlg_Path_Name_T 
format. For more information on this structure, see Path Name Format. 


Related Information 


e The <unistd.h> file (see Header Files for UNIX-Type Functions) 


unlinkQ--Remove Link to File 


e linkQ--Create Link to File 


open()--Open File 


close(Q)--Close File or Socket Descriptor 


e@ rmdir()--Remove Directory 


Example 


See Code disclaimer information for information pertaining to code examples. 


The following example removes a link to a file: This program was stored in a source file with CCSID 37, so 
the constant string "newfile” will be compiled in coded character set identifier (CCSID) 37. Therefore, the 
country or region and language specified are United States English, and the CCSID specified is 37. 


#include <fcntl.h> 
#include <stdio.h> 
#include <Qp0lstdi.h> 


main() { 
const char US_const[3]= "US"; 
const char Language_const [4]="ENU",; 
const char Path_Name_Del_const[2] = "/"; 


struct pnstruct 
{ 
Qlg_Path_Name_T gqlg_struct; 
char pn[7]; 
}; 
struct pnstruct pns; 
struct pnstruct *pns_ptr = NULL; 


char fn[]="unlink.file"; 


memset ((void*)&pns, 0x00, sizeof(struct pnstruct)); 
pns.qlg_struct.CCSID = 37; 
memcpy (pns.qlg_struct.Country_ID,US_const, 2); 
memcpy (pns.qlg_struct.Language_ID, Language_const,3);; 
pns.qlg_struct.Path_Type = 0; 
pns.qlg_struct.Path_Length = sizeof(fn)-1; 
memcpy (pns.qlg_struct.Path_Name_Delimiter, 
Path_Name_Del_const,1); 
memcpy (pns.pn, fn, sizeof (fn)); 
memset ((void *)&Attr_types_ptr, 0x00, 

sizeof(struct attrStruct) ); 
pns_ptr = &pns; 


if (Qp01Unlink ((Qlg_Path_Name_T *)&pns) != 0) 
perror ("QpO0lunlink() error"); 


API introduced: V4R4 


Top | UNIX-Type APIs | APIs by category 


Qp0zPipe()--Create Interprocess Channel with 
Sockets 


Syntax 


#include <spawn.h> 


int QpOzPipe(int fildes[2]); 


Service Program Name: QPOZSPWN 


Default Public Authority: *USE 


Threadsafe: Yes 


The Qp0zPipe() function creates a data pipe that can be used by two processes. One end of the pipe is 
represented by the file descriptor returned in fildes[0]. The other end of the pipe is represented by the file 
descriptor returned in fildes[1]. Data that is written to one end of the pipe can be read from the other end of 
the pipe in a first-in-first-out basis. Both ends of the pipe are open for reading and writing. 


The Qp0zPipe() function is often used with the spawn() function to allow the parent and child processes to 
send data to each other. 


Parameters 


fildes[2] 


(Input) An integer array of size 2 that will contain the pipe descriptors. 


Authorities 


None. 


Return Value 


O Qp0zPipeQ was successful. 


-1 Qp0zPipe( was not successful. The errno variable is set to indicate the error. 


Error Conditions 


If Qp0zPipe() is not successful, errno usually indicates one of the following errors. Under some conditions, 
errno could indicate an error other than those listed here. 


[EFAULT] The address used for an argument is not correct. 


In attempting to use an argument in a call, the system detected an address that is not 
valid. 


While attempting to access a parameter passed to this function, the system detected 
an address that is not valid. 


[EINVAL] The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on 
an object and the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. 
[EIO] Input/output error. 

A physical I/O error occurred. 

A referenced object may be damaged. 
[EMFILE] Too many open files for this process. 


An attempt was made to open more files than allowed by the value of OPEN_MAX. 
The value of OPEN_MAX can be retrieved using the sysconf() function. 


The process has more than OPEN_MAX descriptors already open (see the sysconf() 
function). 


[ENFILE] Too many open files in the system. 


A system limit has been reached for the number of files that are allowed to be 
concurrently open in the system. 


The entire system has too many other file descriptors already open. 


[ENOBUFS] There is not enough buffer space for the requested operation. 


[EOPNOTSUPP] Operation not supported. 


The operation, though supported in general, is not supported for the requested object 
or the requested arguments. 


[EUNKNOWN] Unknown system state. 


The operation failed because of an unknown system state. See any messages in the 
job log and correct any errors that are indicated, then retry the operation. 


Usage Notes 


The OS/400 implementation of the Qp0zPipe(function is based on sockets rather than pipes and, therefore, 
uses socket descriptors. There are several differences: 


1. After calling the fstat() function using one of the file descriptors returned on a QpO0zPipe() call, 
when the st_mode from the stat structure is passed to the S_ISFIFOQ macro, the return value 
indicates FALSE. When the st_mode from the stat structure is passed to S_ISSOCKO, the return 
value indicates TRUE. 


2. The file descriptors returned on a Qp0zPipe() call can be used with the send(), recv(), sendto(), 
recvfrom(), sendmsg(), and recvmsg() functions. 


If you want to use the traditional implementation of pipes, in which the descriptors returned are pipe 
descriptors instead of socket descriptors, use the pipe() function. 


Related Information 
e The <spawn.h> file (see Header Files for UNIX-Type Functions) 


e fstatQ--Get File Information by Descriptor 


pipeQ--Create an Interprocess Channel 


spawn()--Spawn Process 


socketpair()--Create a Pair of Sockets 


e stat()--Get File Information 
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»qsygetgroups()--Get Supplemental Group IDs 


Syntax 


#include <qsysetid.h> 


int gqsygetgroups(int gidsetsize, gid_t grouplist[]) 


Threadsafe: No 


If the gidsetsize argument is zero, qsygetgroups() returns the number of supplemental group IDs associated 
with the calling thread without modifying the array pointed to by the grouplist argument. Otherwise, 
qsygetgroups() fills in the array grouplist with the supplementary group IDs of the calling thread and 
returns the actual number of group IDs stored. The values of array entries with indexes larger than or equal 
to the returned value are undefined. 


Parameters 


gidsetsize 


(Input) The number of elements in the supplied array grouplist. 


grouplist 
(Output) The supplementary group IDs. 


Authorities 


No authorization is required. 


Return Value 


Oor>0O  qsygetgroups() was successful. If the gidsetsize argument is 0, the number of supplementary 
group IDs is returned. If gidsetsize is greater than 0, the array grouplist is filled with the 
supplementary group IDs of the calling thread and the return value represents the actual 
number of group IDs stored. 


-1 qsygetgroups() was not successful. The errno global variable is set to indicate the error. 


Error Conditions 


If qsygetgroups() is not successful, errno usually indicates one of the following errors. Under some 
conditions, errno could indicate an error other than those listed here. 


[EINVAL] The gidsetsize argument is not equal to zero and is less than the number of group IDs. 


€ 
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asysetegid()--Set Effective Group ID 


Syntax 


#include <qsysetid.h> 


int qsysetegid(gid_t gid); 
Threadsafe: Yes 


If gid is equal to either the real, effective, saved group ID, or one of the groups in the supplemental group 
list, qsysetegid() sets the effective group ID to gid. 


If gid is not equal to any of the current groups, but the thread has *USE authority to the user profile 
associated with the gid, qsysetegid() sets the effective group ID to gid. 


Job scoped locks with a lock state of *“SHRRD are held on the user profiles associated with the real user ID, 
effective user ID, saved user ID, real group ID, effective group ID, saved group ID, and all of the 
supplemental groups. 


Parameters 


gid 
(Input) Group ID. 


This field must contain one of the following values: 
0 

There is no effective group ID. 
1 to 4294967294 

The group ID value for the set operation. 


Authorities and Locks 


User profile associated with uid authority 


*USE authority is required to the user profile associated with gid if gid is not equal to the real, 
effective, saved group IDs or one of the groups in the supplemental group list. 


User profile associated with uid lock 
*SHRRD 


Return Value 


0 
qsysetegid() was successful. 
-1 


qsysetegid() was not successful. errno is set to indicate the error. 


Error Conditions 


If qsysetegid() is not successful, errno indicates one of the following errors. 
[EAGAIN] 
User profile associated with the gid is locked. Try again. 
[EINVAL] 
The value of the gid argument is invalid. Following are possible reasons: 
o Out of range. 


o Not associated with a user profile. 


[EDAMAGE] 
The user profile associated with the gid or an internal system object is damaged. 
[ENOTSUP] 


Operation not supported. The current effective user profile specifies OWNER(*GRPPRF), but the 
group profile associated with this gid is not equal to the user profile's first group and the user's first 
group is not in the list of supplemental groups. 


[EPERM] 
Operation not permitted. Following are possible reasons: 


oO The thread does not have *USE authority to the user profile associated with the gid and the 
gid to be set is not the same as the real, effective, saved group IDs or any of the 
supplemental groups. 


oO gid cannot be set to 0 if there are supplemental groups. 


[EUNKNOWN] 


An unknown error has occurred. Check the joblog for error messages. 
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qsyseteuid()--Set Effective User ID 


Syntax 


#include <qsysetid.h> 


int qsyseteuid(uid_t uid); 
Threadsafe: Yes 


If uid is equal to the real, effective, or saved user ID, qsyseteuid() sets the effective user ID to wid. 


If uid is not equal to the real, effective, or saved user ID, but the thread has *USE authority to the user 
profile associated with uid, qsyseteuid() sets the effective user ID to uid. 


Job scoped locks with a lock state of *“SHRRD are held on the user profiles associated with the real user ID, 
effective user ID, saved user ID, real group ID, effective group ID, saved group ID, and all of the 
supplemental groups. 


Parameters 


uid 
(Input) User ID. 
This field must contain one of the following values: 


0 to 4294967294 


The user ID value for the set operation. 


Authorities and Locks 


User profile associated with uid authority 


*USE authority is required to the user profile associated with uid if uid is not equal to the real, 
effective or saved user IDs. 


User profile associated with uid lock 
*SHRRD 


Return Value 


0 
qsyseteuid() was successful. 
-1 


qsyseteuid() was not successful. errno is set to indicate the error. 


Error Conditions 


If qsyseteuid() is not successful, errno indicates one of the following errors. 
[EAGAIN] 

User profile associated with the uid is locked. Try again. 
[EDAMAGE] 

The user profile associated with the wid or an internal system object is damaged. 
[EINVAL] 

The value of the uid argument is invalid. Following are possible reasons: 

o Out of range. 


o Not associated with a user profile. 


[ENOTSUP] 


Operation not supported. The user profile associated with this uid specifies OWNER(*GRPPRF), 
but the user profile's first group is not the current effective group, nor is it in the list of 
supplemental groups. 


[EPERM] 


Operation not permitted. The thread does not have *USE authority to the user profile and the uid to 
be set is not the same as the real, effective, or saved user IDs. 


[EUNKNOWN] 


An unknown error has occurred. Check the joblog for error messages. 
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qsysetgid()--Set Group ID 


Syntax 


#include <qsysetid.h> 


int qsysetgid(gid_t gid); 
Threadsafe: Yes 


If the thread has *ALLOBJ special authority, qsysetgid() sets the real, effective and saved groups to gid. 


If the thread does not have *ALLOBSJ special authority, but gid is equal to the real, effective or saved group 
IDs, the qsysetgid() function sets the effective group ID to gid. The real group and saved group IDs remain 
unchanged. 


Any supplementary group IDs of the calling thread remain unchanged. 


Job scoped locks with a lock state of *“SHRRD are held on the user profiles associated with the real user ID, 
effective user ID, saved user ID, real group ID, effective group ID, saved group ID, and all of the 
supplemental groups. 


Parameters 


gid 
(Input) Group ID. 


This field must contain one of the following values: 
0 


There is no group ID. The effective group ID can be set to 0 only if there are no 
supplemental groups. 


1 to 4294967294 
The group ID value for the set operation. 


Authorities and Locks 


*ALLOBJ special authority 

*ALLOBS special authority is required if gid is not equal to the real, effective or saved group ID. 
User profile associated with gid lock 

*SHRRD 


Return Value 


0 
qsysetgid() was successful. 
-1 


qsysetgid() was not successful. errno is set to indicate the error. 


Error Conditions 


If qsysetgid() is not successful, errno indicates one of the following errors. 
[EAGAIN] 

User profile associated with the gid is locked. Try again. 
[EDAMAGE] 

The user profile associated with the gid or an internal system object is damaged. 
[EINVAL] 

The value of the gid argument is invalid. Following are possible reasons: 

o Out of range. 


o Not associated with a user profile. 


[ENOTSUP] 


Operation not supported. The current effective user profile specifies OWNER(*GRPPRF), but the 
group profile associated with this gid is not equal to the user profile's first group and the user's first 
group is not in the list of supplemental groups. 


[EPERM] 
Operation not permitted. Following are possible reasons: 


oO The thread does not have *ALLOBJ special authority and gid is not the same as the real, 
effective or saved group ID. 


o. Tried to set effective group ID to 0 when there are supplemental groups. 


[EUNKNOWN] 


An unknown error has occurred. Check the joblog for error messages. 
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»qsysetgroups()--Set Supplemental Group IDs 


Syntax 


#include <qsysetid.h> 


int qsysetgroups(int gidsetsize, gid_t grouplist[]) 


Threadsafe: No 


The qsysetgroups API sets the supplementary group IDs of the calling thread. The qsysetgroups API cannot 
set more than (NGROUPS_MAX-1) groups in the group set. 


Parameters 


gidsetsize 


(Input) The number of elements in the supplied array grouplist. 


grouplist 
(Input) The supplementary group IDs. 


Authorities and locks 


User profile associated with gid Authority 


*USE authority is required to the user profile associated with each gid in the group list if the gid is 
not equal to the current thread's real, effective, or saved group IDs or one of the groups in the 
current thread's supplemental group list. 


User profile associated with each gid Lock 
*SHRRD 


Return Value 


0 — qsysetgroups() was successful. 


-1 qsysetgroups() was not successful. The errno global variable is set to indicate the error. 


Error Conditions 


If qsysetgroups() is not successful, errno usually indicates one of the following errors. Under some 
conditions, errno could indicate an error other than those listed here. 


[EAGAIN] 


User profile associated with a gid is locked. Try again. 


[EDAMAGE] 


The user profile associated with a gid or an internal system object is damaged. 


[EINVAL] 
One of the GID values in the grouplist argument is not valid. Following are possible reasons: 
o Out of range. 
o Not associated with a user profile. 


oO. gidsetsize too large. 


[ENOTSUP] 


Operation not supported. The current effective user profile specifies OWNER(*GRPPRF), but the 
user's first group is not equal to the current effective group profile and the user's first group is not in 
this list of supplemental groups. 


[EPERM] 
Operation not permitted. Following are possible reasons: 


oO The thread does not have *USE authority to the user profile associated with the G/D and 
the GID to be set is not the same as the real, effective, saved group IDs or any of the 
supplemental groups. 


oO Supplemental groups cannot be set if effective GID is 0. 


[EUNKNOWN] 
An unknown error has occurred. Check the joblog for error messages. 


€ 
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qsysetregid()--Set Real and Effective Group IDs 


Syntax 


#include <qsysetids.h> 


int gqsysetregid(gid_t rgid, gid_t egid); 
Threadsafe: Yes 


The qsysetregid() function is used to set the real and effective group IDs. The real and effective group IDs 
may be set to different values in the same call. 


A thread with *ALLOBJ special authority can set the real group ID and the effective group ID to any valid 
value. 


A thread without *ALLOBJ special authority can only set the real group ID to the saved group ID. A thread 
without *ALLOBJ special authority can only set the effective group ID to the saved group ID or the real 
group ID. 

Any supplemental group IDs remain unchanged. 

Job scoped locks with a lock state of *“SHRRD are held on the user profiles associated with the real user ID, 


effective user ID, saved user ID, real group ID, effective group ID, saved group ID, and all of the 
supplemental groups. 


Parameters 


real gid 
(Input) Group ID. 


This field must contain one of the following values: 


0 
There is no real group ID. 

1 to 4294967294 
The group ID value for the set operation. 

4294967295 
The real group ID does not change. This value is the same as X'FFFFFFFF' or -1 in 
languages that do not support unsigned integers. 

effective gid 
(Input) Group ID. 


This field must contain one of the following values: 
0 


There is no effective group ID. 


1 to 4294967294 
The group ID value for the set operation. 
4294967295 


The effective group ID does not change. This value is the same as X'FFFFFFFF' or -1 in 
languages that do not support unsigned integers. 


Authorities and Locks 


*ALLOBJ special authority 


*ALLOBS special authority is required to change the real group ID if rgid is not equal to the saved 
group ID. *ALLOBJ special authority is required to set the effective group ID if the egid is not 
equal to the real group ID or the saved group ID. 


User profile associated with rgid lock 
*SHRRD 

User profile associated with egid lock 
*SHRRD 


Return Value 


0 
qsysetregid() was successful. 
-1 


qsysetregid() was not successful. The errno is set to indicate the error. 


Error Conditions 


If qsysetregid() is not successful, errno indicates one of the following errors. 
[EAGAIN] 

User profile associated with the rgid or rgid is locked. Try again. 
[EDAMAGE] 

The user profile associated with one of the gids or an internal system object is damaged. 
[EINVAL] 

The value of the gid argument is invalid. Following are possible reasons: 

o Out of range. 


o Not associated with a user profile. 


[ENOTSUP] 


Operation not supported. The current effective user profile specifies OWNER(*GRPPRP), but the 
group profile associated with this gid is not equal to the user profile's first group and the user's first 
group is not in the list of supplemental groups. 


[EPERM] 
Operation not permitted. Following are possible reasons: 


oO The thread does not have *ALLOBJ special authority and a change other than changing the 
real group ID to the saved group ID, or changing the effective group ID to the real group 
ID or the saved group ID was requested. 


o Tried to set effective group ID to 0 when there are supplemental groups. 


[EUNKNOWN] 


An unknown error has occurred. Check the joblog for error messages. 


Top | UNIX-Type APIs | APIs by category 


qsysetreuid()--Set Real and Effective User IDs 


Syntax 


int gqsysetreuid(uid_t ruid, uid_t euid); 
Threadsafe: Yes 


The qsysetreuid() function sets the real and effective user IDs to the values specified by ruid and euid. 
A thread with *ALLOBJ special authority can set either ID to any value. 


A thread without *ALLOBJ special authority can only set the effective user ID if the euid argument is equal 
to the real, effective, or saved user ID. 


Job scoped locks with a lock state of *“SHRRD are held on the user profiles associated with the real user ID, 
effective user ID, saved user ID, real group ID, effective group ID, saved group ID, and all of the 
supplemental groups. 


Parameters 


real uid 
(Input) User ID. 


This field must contain one of the following values: 
0 to 4294967294 

The user ID value for the set operation. 
4294967295 


The real user ID does not change. This value is the same as X'FFFFFFFF' or -1 in 
languages that do not support unsigned integers. 


effective uid 
(Input) User ID. 


This field must contain one of the following values: 
0 to 4294967294 

The user ID value for the set operation. 
4294967295 


The effective user ID does not change. This value is the same as X'FFFFFFFF' or -1 in 
languages that do not support unsigned integers. 


Authorities and Locks 


*ALLOBJ special authority 


*ALLOBSJ special authority is required to change the real user ID. *ALLOBJ special authorty is 
required to change the effective user ID if the euid is not equal to the real, effective, or saved user 
ID. 


User profile associated with euid lock 
*SHRRD 

User profile associated with ruid lock 
*SHRRD 


Return Value 


0 
qsysetreuid() was successful. 
-1 


qsysetreuid() was not successful. The errno variable is set to indicate the error. 


Error Conditions 


If qsysetreuid() is not successful, errno indicates one of the following errors. 
[EAGAIN] 

User profile associated with ruid or euid is locked. Try again. 
[EDAMAGE] 

The user profile associated with ruid or euid or an internal system object is damaged. 
[EINVAL] 

The value of the ruid or euid argument is invalid. Following are possible reasons: 

o Out of range. 


o Not associated with a user profile. 


[ENOTSUP] 


Operation not supported. The user profile associated with this uid specifies OWNER(*GRPPRF), 
but the user profile's first group is not the current effective group, nor is it in the list of 
supplemental groups. 


[EPERM] 


Operation not permitted. The current thread does not have *ALLOBJ special authority, and either 
an attempt was made to change the effective user ID to a value other than the real user ID or the 
saved set-user-ID or an an attempt was made to change the real user ID. 


[EUNKNOWN] 


An unknown error has occurred. Check the joblog for error messages. 
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qsysetuid()--Set User ID 


Syntax 


#include <qsysetid.h> 


int qsysetuid(uid_t uid); 
Threadsafe: Yes 


If the thread has *ALLOBJ special authority, qsysetuid() sets the real, effective, and saved user ID to wid. 


If the thread does not have *ALLOBS special authority, but wid is equal to the real, effective or saved user 
ID, qsysetuid() sets the effective user ID to uid. The real and saved user IDs remain unchanged. 


Job scoped locks with a lock state of *“SHRRD are held on the user profiles associated with the real user ID, 
effective user ID, saved user ID, real group ID, effective group ID, saved group ID, and all of the 
supplemental groups. 


Parameters 


uid 
(Input) User ID. 
This field must contain one of the following values: 


0 to 4294967294 


The user ID value for the set operation. 


Authorities and Locks 


*ALLOBJ special authority 

*ALLOBJ special authority is required if wid is not equal to the real, effective, or saved user ID. 
User profile associated with uid lock 

*SHRRD 


Return Value 


0 
qsysetuid() was successful. 
-1 


qsysetuid() was not successful. errno is set to indicate the error. 


Error Conditions 


If qsysetuid() is not successful, errno indicates one of the following errors. 
[EAGAIN] 

User profile associated with the uid is locked. Try again. 
[EDAMAGE] 

The user profile associated with the wid or an internal system object is damaged. 
[EINVAL] 

The value of the wid is invalid. Following are possible reasons: 

o Out of range. 


o Not associated with a user profile. 


[ENOTSUP] 


Operation not supported. The user profile associated with this uid specifies OWNER(*GRPPRF), 
but the user profile's first group is not the current effective group, nor is it in the list of 
supplemental groups. 


[EPERM] 


Operation not permitted. The thread does not have *ALLOBJ special authority and wid is not the 
same as the real, effective or saved user ID. 


[EUNKNOWN] 


An unknown error has occurred. Check the joblog for error messages. 
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Retrieve Network File System Export Entries 
(QZNFRTVE) API 


Required Parameter Group: 


Receiver variable Output Char(*) 
Length of receiver variable in bytes Input Binary(4) 
Returned records feedback information Output Char(16) 
Format name Input Char(8) 
Object path name Input Char(*) 
Length of object path name in bytes Input Binary(4) 
CCSID of object path name given Input Binary(4) 


Desired CCSID of the object path Input Binary(4) 
names returned 


Handle Input Binary(4) 
Error code 1/O Char(**) 


1 
2 
3 
4 
5 
6 
7 
8 


Threadsafe: No 


The Retrieve Network File System Export Entries (QZNFRTVE) API returns the list of Network File 
System (NFS) export entries for objects currently exported to NFS clients or for objects referenced in the 
/etc/exports file. 


Authorities and Locks 


e The user must have execute (*X) data authority to the /etc directory (if it exists). 


e The user must have read (*R) data authority to the /etc/exports file (if it exists). 


Note: Adopted authority is not used. 


Usage Notes 


If none of the required parameters are passed to this API, then all of the entries that are currently exported 
will be returned to the joblog by messages (CPIB41A). If there are no entries currently exported, then 
message CPIB41B will be returned. 


Required Parameter Group 


The following parameters are required. 
Receiver variable 
OUTPUT; CHAR(*) 


The receiver variable that receives the information requested. The API returns only data that the 
area can hold. 


Length of receiver variable 
INPUT; BINARY(4) 


The length of the receiver variable provided. The length of the receiver variable parameter may be 
specified up to the size of the receiver variable area specified by the user program. 


No partial entries will be returned. If the length of the receiver variable is less than what is required 


by the format selected, then an error is returned (CPFB419) and the size required will be indicated 
in the feedback structure. 


Returned records feedback information 
OUTPUT; CHAR(16) 


Information about the entries that are returned in the receiver variable. 


For a detailed description of this format, see Format of Returned Records Feedback Information. 


Format name 
INPUT; CHAR(8) 


The name of the format that is used to retrieve NFS export entries. 


You can specify one of the following formats: 
EXPE0100 


Returns information about export entries that are currently exported. These are sometimes 
called temporary exports. For a detailed description of this format, see EXPEO100 and 


EXPE0200 format. 
EXPE0200 


Returns information about export entries that are in the /etc/exports file. These are 
sometimes called permanent exports. For a detailed description of this format, see 
EXPE0100 and EXPE0200 format. 


Object path name 
INPUT; CHAR(*) 


The object path name at which to start listing NFS export entries. Possible values follow: 
*FIRST 


NES export entries are returned starting with the first object path name in the NFS export 
entry list. 


*HANDLE 


NES export entries are returned starting with the object path name that corresponds to the 
specified handle. 


When the receiver variable is not large enough to hold all of the entries in the NFS export 
entry list, the API returns a non-zero handle in the returned records feedback information 
parameter. This handle can be used on a subsequent call to the API to continue retrieving 
NES export entries with the next object path name in the NFS export entry list. 


There is no implied order to the export entries that are returned. While no sorting or 


sequencing has been done on the returned entries, a complete list will eventually be 
returned if the *HANDLE option is used. 


Object path name 
The NFS export entry for the specified object path name is returned. 


Length of object path name 
INPUT; BINARY(4) 


The length of the object path name in bytes. If one of the special values is given for the object path 
name, then the length should be given for that special value. 


CCSID of object path name given 
INPUT; BINARY(4) 


The CCSID of the object path name given as an input parameter. Possible values follow: 
0 

The current Default Job CCSID should be used. 
value 

A valid CCSID number. 


Desired CCSID of object the path names returned. 
INPUT; BINARY(4) 
The Desired CCSID of the object path names returned. The output structure will contain the actual 


CCSID of the returned object path names. This will match the Desired CCSID given as input, if 
possible. Possible values follow: 


0 

The current Default Job CCSID should be used. 
value 

A valid CCSID number. 


Handle of starting object path name 
INPUT; BINARY(4) 


The handle returned from a previous call to the QZNFRTVE API. 


This parameter should be 0 if “HANDLE was NOT specified for the object path name parameter. 


Error code 
1V/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see . 


Receiver Variable Description 


The following table describes the order and format of the data returned in the receiver variable. For a 
detailed description of each field, see Field Descriptions. 


EXPE0100 and EXPE0200 format 


This structure is used to return NFS export information for a single object path name for both the 
EXPEO0100 and the EXPE0200 formats. 


| Offset 
a c | Hex |Type Field 


[ 8 [| 8 J|BINARY(4) [Length of objectpathname = == 
| 12 [ C  |BINARY() — |CCSID of objectpathname = 
| 16 | 10 |BINARY(4) [Read-onlyflag 9 
[20 | 14 [BINARY |NOSUID flag 

| 24 | 18 |BINARY(4) [Displacement to read-write hostnames 
; 28 [ic |BINARY(@) Number of read-write host names 

| 32 [ 20 |BINARY(4) — [Displacementtoroothostnames = 
[ 36 [| 24 |BINARY(@) — Number of root host names 

| 40 | 28 |BINARY(4) [Displacement toaccesshostnames == 
| 44 [| 2C |BINARY(4) — Number of access host names 

| 48 | 30 |BINARY(4)  [Displacementtohost options = 
| 52 | 34 |BINARY(4) [Number ofhostoptions == 
| 56 [ 38 |BINARY(4) |AnonymoususerID = = = 
| 60 | 3C {CHAR(0) ~~ [Anonymous UserProfile = = == 


These fields [BINARY (4) Length of host name entry 
repeat for each 
host name in the [BINARY (4) [Fength of host name 


ieadewotte access CHAR @) Hostname 
These fields [BINARY (4) [Length of host name entry 

repeat for each = [Length ofhostname ——SSSSOS™S 
ia nae BINARY(4) Length of host name 

root access list. [CHAR(*) [Host name 

These fields BINARY(4) [Length of host name entry 

repeat for each IBINARYG) [Length ofhostmame SSCS 
Rane ane BINARY(4) Length of host name 

access list. CHAR(*) Host name 


These fields [BINARY(4) [Length of host name options entry 


repeat foreach = [BINARY(4) _ [Network data file CCSID 

host name in the N 

host options list. [BIN ARY(4) [Network path name CCSID 
[BINARY(4) [Write mode flag 
[BINARY(4) [Length of host name 


| CHAR(*) Host name | 


Returned Records Feedback Information Description 


The following table describes the order and format of the data returned in the returned records feedback 
information parameter. For a detailed description of each field, see Field Descriptions. 


Format of Returned Records Feedback Information 


| Offset 
| Dec Hex /Type Field 


| 0 0 BINARY(4) Bytes returned 

| 4 4 BINARY(4) Bytes available 

| 8 8 BINARY(4) Number of NFS export entries 
| 12 C BINARY(4) Handle 


Field Descriptions 


Anonymous User ID. The user ID used as the effective user ID for requests from unknown users. Hex 
value OXFFFFFFFF (a value of -1 if this were a signed integer) indicates requests from unknown users are 
not allowed. 


Anonymous User Profile. This is the OS/400 User Profile name that is associated with the Anonymous 
User ID returned. If the Anonymous User ID has the special value of hex value OXFFFFFFFF (a value of -1 
if this were a signed integer), then the Anonymous User Profile will be set to the special value of *NONE. 


Bytes available. The number of bytes of data available to be returned to the user in the receiver variable. If 
all data is returned, bytes available is the same as the number of bytes returned. If the receiver variable was 
not large enough to contain all of the data, this value is estimated based on the total number of entries in the 
NES export entry list that could be returned. 

Bytes returned. The number of bytes of data returned to the user in the receiver variable. 

CCSID of object path name. The CCSID of the object path name. 


Object path name. The path name of the object for which export information is to be returned. 


Displacement to access host names. The offset (in bytes) from the beginning of the NFS export entry to 
the host names in the access list. 


Displacement to host options. The offset (in bytes) from the beginning of the NFS export entry to the host 
options list. 


Displacement to object path name. The offset (in bytes) from the beginning of the NFS export entry to 
the object path name. 


Displacement to read-write host names. The offset (in bytes) from the beginning of the NFS export entry 
to the host names in the read-write access list. 


Displacement to root host names. The offset (in bytes) from the beginning of the NFS export entry to the 
host names in the root access list. 


Handle. The handle to be used on a subsequent call to the API to continue retrieving NFS export entries 
with the next object path name in the NFS export entry list. 0 indicates all remaining NFS export entries 
have been returned. 


Host name. The host name. 


Length of entry. The length (in bytes) of the current NFS export entry. The length can be used to access 
the next entry. 


Length of host name. The length (in bytes) of the host name. 

Length of host name entry. The length (in bytes) of this host name entry. 

Length of host name options entry. The length (in bytes) of this host name options entry. 
Length of object path name. The length (in bytes) of the object path name. 


Network data file CCSID. The CCSID used for data of the files sent to and received from the specified 
host name. 


Network path name CCSID. The CCSID used for path name components of the files sent to and received 
from the specified host name. 


NOSUID flag. Whether an attempt by the client to enable bits other than the permission bits will be 
ignored. Possible values follow: 


0 


An attempt to set bits other than the permission bits will be carried out. 


An attempt to set bits other than the permission bits will be ignored. 
Number of access host names. The number of host names in the access list. 
Number of host options. The number of entries in the host options list. 


Number of NFS export entries. The number of complete entries returned in the list of NFS export entries. 
A value of zero is returned if the list is empty relative to the requested starting position. 


Number of read-write host names. The number of host names in the read-write access list. 


Number of root host names. The number of host names in the root access list. 


Read-only flag. Whether the object is exported allowing only read access. Possible values follow: 
0 


The object is exported allowing read-write access for all client hosts that are not specifically 
indicated to have read-only access. 


The object is exported allowing read-only access for all client hosts that are not specifically 
indicated to have read-write access. 


Write mode flag. Whether write requests are handled synchronously or asynchronously. Synchronously 
means that data will be written to disk immediately. Asynchronously does not guarantee that data is written 


to disk immediately, and can be used to improve server performance. Possible values follow: 
0 


Write requests are performed synchronously. 


Write requests are performed asynchronously. 


Error Messages 


CPE3418 E 
Possible APAR condition or hardware failure. 
CPF3C90 E 
Literal value cannot be changed. 
CPF3CF2 E 
Error(s) occurred during running of &1 API. 
CPF9872 E 
Program or service program &1 in library &2 ended. Reason code &3. 
CPFAO0D4 E 


File system error occurred. 
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read()--Read from Descriptor 


Syntax 


#include <unistd.h> 


ssize_t read(int file_descriptor, 
void *buf, size_t nbyte); 


Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


From the file or socket indicated by file_descriptor, the read() function reads nbyte bytes of input into the 
memory area indicated by buf. If nbyte is zero, read() returns a value of zero without attempting any other 
action. 


If file_descriptor refers to a "regular file" (a stream file that can support positioning the file offset) or any 
other type of file on which the job can do an Iseek() operation, read() begins reading at the file offset 
associated with file_descriptor. A successful read() changes the file offset by the number of bytes read. 


If read() is successful and nbyte is greater than zero, the access time for the file is updated. 
read() is not supported for directories. 


If file_descriptor refers to a descriptor obtained using the open() function with O_TEXTDATA specified, 
the data is read from the file assuming it is in textual form. The maximum number of bytes on a single read 
that can be supported for text data is 2,147,483,408 (2GB - 240) bytes. The data is converted from the code 
page of the file to the code page of the application, job, or system as follows: 


e When reading from a true stream file, any line-formatting characters (such as carriage return, tab, 
and end-of-file) are just converted from one code page to another. 


e When reading from record files that are being used as stream files, end-of-line characters are added 
to the end of the data in each record. 


There are some important considerations when the file is open for text conversion and the CCSIDs involved 
are not strictly single-byte: 


e The read() will return the exact number of bytes requested. For some CCSIDs, this may mean that 
partial characters are returned at the end of the user buffer. In this case, the remainder of the 
character has been read from the file and internally buffered. The next consecutive read() will begin 
with the remainder of the partial character. However, if an Iseek() is performed, the buffered data 
will be discarded. See lseek()--Set File Read/Write Offset for more information. 


e Because of the above consideration and because of the possible expansion or contraction of 
converted data, applications using the O_CCSID flag should avoid assumptions about data size and 
the current file offset. For example, a file might have a physical size of 100 bytes, but after an 
application has read 100 bytes from the file, the current file offset may be 50. In order to read the 
whole file, the application might have to read 200 bytes or more, depending on the CCSIDs 
involved. 


If O_TEXTDATA was not specified on the open(), the data is read from the file without conversion. The 
application is responsible for handling the data. 


In the QSYS.LIB #*and independent ASP QSYS.LIB file systems, {most end-of-file characters are 
symbolic; that is, they are stored outside the member. When reading: 


e If O_TEXTDATA is specified, both symbolic and nonsymbolic end-of-file characters can be seen. 


e If O_TEXTDATA is not specified (binary mode), only nonsymbolic end-of-file characters can be 
seen. 


See the Usage Notes for write()--Write to Descriptor. 


When file_descriptor refers to a socket, the read() function reads from the socket identified by the socket 
descriptor. 


When attempting to read from an empty pipe or FIFO: 
e If no job has the pipe or FIFO open for writing, read() return 0 to indicate end-of-file. 


e If some job has the pipe or FIFO open for writing and O_NONBLOCK was specified, read() will 
fail and errno will be set to [EAGAIN]. 


e If some job has the pipe or FIFO open for writing and O_NONBLOCK was not specified, read() 
will block the calling thread until some data is written or until the pipe or FIFO is closed by all jobs 
that had the pipe or FIFO open for writing. 


Parameters 


file_descriptor 
(Input) The descriptor to be read. 


buf 

(Output) A pointer to a buffer in which the bytes read are placed. 
nbyte 

(Input) The number of bytes to be read. 
Authorities 


No authorization is required. 


Return Value 


value 
read() was successful. The value returned is the number of bytes actually read and placed in buf. 
This number is less than or equal to nbyte. It is less than nbyte only if read() reached the end of the 
file before reading the requested number of bytes. If read() is reading a regular file and encounters 
a part of the file that has not been written (but before the end of the file), read() places bytes 
containing zeros into buf in place of the unwritten bytes. 

-1 


read() was not successful. The errno global variable is set to indicate the error. If the value of nbyte 
is greater than SSIZE_MAX, read() sets errno to [EINVAL]. 


Error Conditions 


If readQ(Q) is not successful, errno usually indicates one of the following errors. Under some conditions, 
errno could indicate an error other than those listed here. 


[EACCES] 


[EAGAIN] 


[EBADF] 


[EBADFID] 


[EBUSY] 


[EDAMAGE] 


Permission denied. 


An attempt was made to access an object in a way forbidden by its object access 
permissions. 


The thread does not have access to the specified file, directory, component, or path. 


If you are accessing a remote file through the Network File System, update operations 
to file permissions at the server are not reflected at the client until updates to data that 
is stored locally by the Network File System take place. (Several options on the Add 
Mounted File System (ADDMFS) command determine the time between refresh 
operations of local data.) Access to a remote file may also fail due to different 
mappings of user IDs (UID) or group IDs (GID) on the local and remote systems. 


This may occur if file_descriptor refers to a socket and the socket is using a 
connection-oriented transport service, and a connect() was previously completed. The 
thread, however, does not have the appropriate privileges to the objects that were 
needed to establish a connection. For example, the connect() required the use of an 
APPC device that the thread was not authorized to. 


Operation would have caused the process to be suspended. 


If file_descriptor refers to a pipe or FIFO that has its O_NONBLOCK flag set, this 
error occurs if the read() would have blocked the calling thread. 


Descriptor not valid. 


A file descriptor argument was out of range, referred to a file that was not open, or a 
read or write request was made to a file that is not open for that operation. 


A given file descriptor or directory pointer is not valid for this operation. The 
specified descriptor is incorrect, or does not refer to an open file. Or, this read request 
was made to a file that was only open for writing. 

A file ID could not be assigned when linking an object to a directory. 


The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as 
possible. 


Resource busy. 
An attempt was made to use a system resource that is not available at this time. 
A damaged object was encountered. 


A referenced object is damaged. The object cannot be used. 


[EFAULT] 


2[EINTR] 


[EINVAL] 


[EIO] 


[ENOMEM] 


[ENOTAVAIL] 


[ENOTSAFE] 


#[ENXIO] 


[EOVERFLOW] 


#[ERESTART] 


The address used for an argument is not correct. 


In attempting to use an argument in a call, the system detected an address that is not 
valid. 


While attempting to access a parameter passed to this function, the system detected an 
address that is not valid. 


Interrupted function call.“ 


The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on 
an object and the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. 


This may occur if file_descriptor refers to a socket that is using a connectionless 
transport service, is not a socket of type SOCK_RAW, and is not bound to an address. 


The file resides in a file system that does not support large files, and the starting 
offset of the file exceeds 2GB minus 2 bytes. 


Input/output error. 

A physical I/O error occurred. 

A referenced object may be damaged. 

Storage allocation request failed. 

A function needed to allocate storage, but no storage is available. 
There is not enough memory to perform the requested function. 
Independent Auxiliary Storage Pool (ASP) is not available. 


The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage 
(RCLSTG) processing. 


To recover from this error, wait until processing has completed for the independent 
ASP. 


Function is not allowed in a job that is running with multiple threads. 
No such device or address.*& 


Object is too large to process. 
The object's data size exceeds the limit allowed by this function. 


The file is a regular file, nbyte is greater than 0, the starting offset is before the 
end-of-file, and the starting offset is greater than or equal to 2GB minus 2 bytes. 


A system call was interrupted and may be restarted. 


[ESTALE] File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may have 
been deleted at the server. 


[EUNKNOWN] Unknown system state. 


The operation failed because of an unknown system state. See any messages in the 
job log and correct any errors that are indicated, then retry the operation. 


When the descriptor refers to a socket, errno could indicate one of the following errors: 


[ECONNABORTED] 


[ECONNREFUSED] 


[ECONNRESET] 


[EINTR] 


[ENOTCONN] 


[ETIMEDOUT] 


[EUNATCH] 


[EWOULDBLOCK] 


Connection ended abnormally. 


This error code indicates that the transport provider ended the connection 
abnormally because of one of the following: 


e The retransmission limit has been reached for data that was being sent on 
the socket. 


e A protocol error was detected. 


The destination socket refused an attempted connect operation. 


A connection with a remote socket was reset by that socket. 


Interrupted function call. 


Requested operation requires a connection. 


This error code is returned only on sockets that use a connection-oriented 
transport service. 


A remote host did not respond within the timeout period. 


A non-blocking connect() was previously completed that resulted in the 
connection timing out. No connection is established. This error code is returned 
only on sockets that use a connection-oriented transport service. 


The protocol required to support the specified address family is not available at 
this time. 


Operation would have caused the process to be suspended. 


If interaction with a file server is required to access the object, errno could indicate one of the following 


errors: 


[EADDRNOTAVAIL] Address not available. 


[ECONNABORTED] 


Connection ended abnormally. 


[ECONNREFUSED] 


[ECONNRESET] 


[EHOSTDOWN] 


[EHOSTUNREACH] 


[ENETDOWN] 


[ENETRESET] 


[ENETUNREACH] 


[ESTALE] 


[ETIMEDOUT] 


[EUNATCH] 


Error Messages 


The destination socket refused an attempted connect operation. 

A connection with a remote socket was reset by that socket. 

A remote host is not available. 

A route to the remote host is not available. 

The network is not currently available. 

A socket is connected to a host that is no longer available. 

Cannot reach the destination network. 

File or object handle rejected by server. 

If you are accessing a remote file through the Network File System, the file may 
have been deleted at the server. 


A remote host did not respond within the timeout period. 


The protocol required to support the specified address family is not available at 
this time. 


The following messages may be sent from this function: 


Message ID Error Message Text 


CPE3418 E Possible APAR condition or hardware failure. 


CPF3CF2 E Error(s) occurred during running of &1 API. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFAO081 E Unable to set return value or error code. 


CPFA0D4 E File system error occurred. Error number &1. 


Usage Notes 


1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 
o Where multiple threads exist in the job. 


o The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


m Root 

m QOpenSys 

m User-defined 

wg QNTC 

mw QSYS.LIB 

m Independent ASP QSYS.LIB & 
gw QOPT 


2. QSYS.LIB #and Independent ASP QSYS.LIB “File System Differences 


This function will fail with error code [ENOTSAFE] if the object on which this function is 
operation is a save file and multiple threads exist in the job. 


This function will fail with error code [EIO] if the file specified is a save file and the file does not 
contain complete save file data. 


The file access time for a database member is updated using the normal rules that apply to database 
files. At most, the access time is updated once per day. 


If you previously used the integrated file system interface to manipulate a member that contains an 
end-of-file character, you should avoid using other interfaces (such as the Source Entry Utility or 
database reads and writes) to manipulate the member. If you use other interfaces after using the 
integrated file system interface, the end-of-file information will be lost. 


3. QOPT File System Differences 
The file access time is not updated on a read() operation. 


When reading from files on volumes formatted in Universal Disk Format (UDF), byte locks on the 
range being read are ignored. 


4. Network File System Differences 


Local access to remote files through the Network File System may produce unexpected results due 
to conditions at the server. Once a file is open, subsequent requests to perform operations on the 
file can fail because file attributes are checked at the server on each request. If permissions on the 
file are made more restrictive at the server or the file is unlinked or made unavailable by the server 
for another client, your operation on an open file descriptor will fail when the local Network File 
System receives these updates. The local Network File System also impacts operations that retrieve 
file attributes. Recent changes at the server may not be available at your client yet, and old values 
may be returned from operations. (Several options on the Add Mounted File System (ADDMFS) 
command determine the time between refresh operations of local data.) 


Reading and writing to files with the Network File System relies on byte-range locking to 
guarantee data integrity. To prevent data inconsistency, use the fentl() API to get and release these 
locks. 


5. QFileSvr.400 File System Differences 


The largest buffer size allowed is 16 megabytes. If a larger buffer is passed, the error EINVAL will 
be received. 


6. For sockets that use a connection-oriented transport service (for example, sockets with a type of 
SOCK_STREAM), a return value of zero indicates one of the following: 


oO The partner program has issued a close() for the socket. 
o The partner program has issued a shutdown() to disable writing to the socket. 
o The connection is broken and the error was returned on a previously issued socket function. 


o A shutdown() to disable reading was previously done on the socket. 


7. The following applies to sockets that use a connectionless transport service (for example, a socket 
with a type of SOCK_DGRAM). 


o. If a connect() has been issued previously, then data can be received only from the address 
specified in the previous connect(). 


o The address from which data is received is discarded, since the read() has no address 
parameter. 


o The entire message must be read in a single read operation. If the size of the message is too 
large to fit in the user supplied buffer, the remaining bytes of the message are discarded. 


o A returned value of zero indicates one of the following: 
m The partner program has sent a NULL message (a datagram with no user data). 
a A shutdown() to disable reading was previously done on the socket. 


m The buffer length specified was zero. 


8. For file systems that do not support large files, read() will return [EINVAL] if the starting offset 
exceeds 2GB minus 2 bytes, regardless of how the file was opened. For the file systems that do 
support large files, read() will return [EOVERFLOW] if the starting offset exceeds 2GB minus 2 
bytes and the file was not opened for large file access. 


9. Using this function successfully on the 4*/dev/null or /dev/zero “Kcharacter special file results in a 


return value of zero. In addition, the access time for the file is updated. 


Related Information 


e The <limits.h> file (see Header Files for UNIX-Type Functions) 
e The <unistd.h> file (see Header Files for UNIX-Type Functions) 


@ creat()--Create or Rewrite File 


e dupQ--Duplicate Open File Descriptor 


e dup2(--Duplicate Open File Descriptor to Another Descriptor 


e fcntlQ--Perform File Control Command 


e ioctl)--Perform I/O Control Request 
e@ lseek()--Set File Read/Write Offset 


@ open()--Open File 

@ =pread()--Read from Descriptor with Offset 

@ pread64()--Read from Descriptor with Offset (large file enabled) 
e pwrite()--Write to Descriptor with Offset 

e pwrite64()--Write to Descriptor with Offset (large file enabled) 


e readv()--Read from Descriptor Using Multiple Buffers 


@ recv()--Receive Data 


e recvfrom()--Receive Data 


e recvmsg()--Receive Data or Descriptors or Both 


@ write()--Write to Descriptor 


@ writev(Q--Write to Descriptor Using Multiple Buffers 


Example 


The following example opens a file and reads input: 


#include <stdio.h> 
#include <unistd.h> 
#include <fcntl.h> 


main() { 
int ret, file_descriptor, rc; 
char buf[]="Test text"; 


if ((file_descriptor = creat ("test.output", S_IWUSR))!= 0) 
perror("creat() error"); 
else { 
if (-1l==(rce=write(file_descriptor, buf, sizof(buf)-1))) 
perror("write() error"); 
if (close(file_descriptor) != 0) 
perror("close() error"); 


} 


if ((file_descriptor = open("test.output", O_RDONLY)) < 0) 
perror ("open() error"); 
else { 
ret = read(file_descriptor, buf, sizeof (buf)-1)); 
buf[ret] = 0x00; 
printf ("block read: \n<%s>\", buf); 
if (close(file_descriptor) != 0) 
perror("close() error"); 


if (unlink ("test.output") != 0) 
perror("unlink() error"); 


} 
Output: 


block read: 
<Test text> 


API introduced: V3R1 
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readdir()--Read Directory Entry 


Syntax 


#include <sys/types.h> 
#include <dirent.h> 


struct dirent *readdir(DIR *dirp); 


Threadsafe: No; see Usage Notes. 


The readdir() function returns a pointer to a dirent structure describing the next directory entry in the 
directory stream associated with dirp. 


A call to readdir() overwrites data produced by a previous call to readdir() on the same directory stream. 
Calls for different directory streams do not overwrite the data of each other. 


If the call to readdir() actually reads the directory, the access time of the directory is updated. 


readdir() performs translation if necessary to convert the directory entry name into the CCSID (coded 
character set identifier) of the job at the time of the call to opendir(). 


Parameters 


dirp 
(Input) A pointer to a DIR that refers to theopen directory stream to be read. This pointer is 


returned by opendir() (see opendir()--Open Directory). 


See QlgReaddirQ--Read Directory Entry for a description and an example of supplying the dirp in 
any CCSID, using a dirent_Ig structure. 


A dirent structure has the following contents: 


char d_reserved1[16] Reserved. 

unsigned int d_fileno_gen_id The generation ID associated with the file ID. 

ino_t d_fileno The file ID of the file. This number uniquely identifies the 
object within a file system. 

unsigned int d_reclen The length of the directory entry in bytes. 

int d_reserved3 Reserved. 

char d_reserved4[6] Reserved. 


char d_reserved5[2] Reserved. 


qlg_nls_t d_nlsinfo National language information about d_name. The following 
fields are defined: 


int ccsid 
CCSID of the characters in the d_name field. 
char country_id[2] 


Country or region identifier associated with the 
d_name field. 


char language_id[3] 
Language identifier associated with the d_name field. 


char nls_reserved[3] 


Reserved. 
unsigned int d_namelen The length of the name in bytes, excluding the null terminator. 
char d_name[640] A string that gives the name of a file in the directory. This 


string ends in a terminating null, and has a maximum length of 
{NAME_MAX} bytes, not including the terminating NULL 
(see pathconf()--Get Configurable Path Name Variables). 


Authorities 


No authorization is required. Authorization is verified during opendir(). 


Return Value 


value 


readdir() was successful. The value returned is a pointer to a dirent structure describing the next 
directory entry in the directory stream. 


NULL pointer 


One of the following has occurred: 


oO readdir() reached the end of the directory stream. The errno global variable is not 
changed. 


o readdir() was not successful. The errno is set. 


Error Conditions 


If readdir() is not successful, errno usually indicates one of the following errors. Under some conditions, 
errno could indicate an error other than those listed here. 


[EACCES] 


Permission denied. 
An attempt was made to access an object in a way forbidden by its object access permissions. 


The thread does not have access to the specified file, directory, component, or path. 


If you are accessing a remote file through the Network File System, update operations to file 
permissions at the server are not reflected at the client until updates to data that is stored locally by 
the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) 
command determine the time between refresh operations of local data.) Access to a remote file may 
also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote 
systems. 


[EAGAIN] 


Operation would have caused the process to be suspended. 
[EBADFID] 

A file ID could not be assigned when linking an object to a directory. 

The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as possible. 


[EBADF] 


Descriptor not valid. 


A file descriptor argument was out of range, referred to a file that was not open, or a read or write 
request was made to a file that is not open for that operation. 


A given file descriptor or directory pointer is not valid for this operation. The specified descriptor is 
incorrect, or does not refer to an open file. 


[EBUSY] 


Resource busy. 


An attempt was made to use a system resource that is not available at this time. 


[EDAMAGE] 


A damaged object was encountered. 


A referenced object is damaged. The object cannot be used. 


[EFAULT] 


The address used for an argument is not correct. 
In attempting to use an argument in a call, the system detected an address that is not valid. 
While attempting to access a parameter passed to this function, the system detected an address that 


is not valid. 


[EINVAL] 


The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on an object and 


the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. 


[EIO] 
Input/output error. 
A physical I/O error occurred. 
A referenced object may be damaged. 
[ENOSPC] 
No space available. 
The requested operations required additional space on the device and there is no space left. This 
could also be caused by exceeding the user profile storage limit when creating or transferring 
ownership of an object. 
Insufficient space remains to hold the intended file, directory, or link. 
[ENOTAVAIL] 
Independent Auxiliary Storage Pool (ASP) is not available. 
The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage (RCLSTG) 
processing. 
To recover from this error, wait until processing has completed for the independent ASP. 
[ENOTSAFE] 
Function is not allowed in a job that is running with multiple threads. 
[ESTALE] 
File or object handle rejected by server. 
If you are accessing a remote file through the Network File System, the file may have been deleted 
at the server. 
[EUNKNOWN] 


Unknown system state. 


The operation failed because of an unknown system state. See any messages in the job log and 
correct any errors that are indicated, then retry the operation. 


If interaction with a file server is required to access the object, errno could indicate one of the following 
errors: 
[EADDRNOTAVAIL] 
Address not available. 
[ECONNABORTED] 


Connection ended abnormally. 


[ECONNREFUSED] 
The destination socket refused an attempted connect operation. 
[ECONNRESET] 
A connection with a remote socket was reset by that socket. 
[EHOSTDOWN] 
A remote host is not available. 
[EHOSTUNREACH] 
A route to the remote host is not available. 
[ENETDOWN] 
The network is not currently available. 
[ENETRESET] 
A socket is connected to a host that is no longer available. 
[ENETUNREACH] 
Cannot reach the destination network. 
[ESTALE] 
File or object handle rejected by server. 
If you are accessing a remote file through the Network File System, the file may have been deleted 
at the server. 
[ETIMEDOUT] 
A remote host did not respond within the timeout period. 
[EUNATCH] 


The protocol required to support the specified address family is not available at this time. 


Error Messages 


The following messages may be sent from this function: 


CPE3418 E Possible APAR condition or hardware failure. 

CPFAOD4E _ File system error occurred. Error number &1. 

CPF3CF2 E Error(s) occurred during running of &1 API. 

CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 


1. The readdir_r(Q) API should be used to read a directory when running in a multithreaded job. 


2. Save the data from readdir(), if required, before calling closedir(), because closedir() frees the 
data. 


3. If the dirp argument passed to readdir() does not refer to an open directory stream, readdir() 
returns the [EBADF] error. 


4. readdir() buffers multiple directory entries to improve performance. This means the directory is 
not actually read on each call to readdir(). As a result, files that are added to the directory after 


opendir() or rewinddir() may not be returned on calls to readdir(), and files that are removed may 
still be returned on calls to readdir(). 


5. readdir() also returns directory entries for dot (.) and dot-dot (..) subdirectories. 
6. QSYS.LIB #and Independent ASP QSYS.LIB *&File System Differences 


Calls to readdir() that update the access time of the directory use the normal rules that apply to 
libraries and database files. At most, the access time is updated once per day. 
7. QDLS File System Differences 


The access time of the directory is updated on opendir(). The access time is not affected by 
readdir(). 


When objects in QDLS are accessed, the country or region ID and language ID of the directory 
entry name are always set to the country or region ID and language ID of the system. 


When a readdir() operation specifies the /QDLS directory, the user must have *USE authority to 
each child object of the /QDLS directory (that is, *USE authority to each object immediately below 
QDLS in the directory hierarchy). A directory entry is returned only for those objects for which the 
user has *USE authority. If the readdir() operation specifies a directory below QDLS, a directory 
entry is returned for all objects, even if the user does not have *USE authority for some of the 
objects. 


8. QOPT File System Differences 


The access time of the directory is not updated on a readdir() operation. 


Related Information 


e The <sys/types.h> file (see Header Files for UNIX-Type Functions) 


e The <dirent.h> file see Header Files for UNIX-Type Functions) 


@ opendir(--Open Directory 


e QlgReaddir()--Read Directory Entry 


e@ rewinddirQ--Reset Directory Stream to Beginning 


e closedirQ--Close Directory 
e pathconf()--Get Configurable Path Name Variables 


Example 


The following example reads the contents of a root directory: 


#include <sys/types.h> 
#include <dirent.h> 
#include <errno.h> 
#include <stdio.h> 


main() { 
DIR *dir; 
struct dirent *entry; 


if ((dir = opendir("/")) == NULL) 
perror ("opendir() error"); 
else { 
puts ("contents of root:"); 
while ((entry = readdir(dir)) != NULL) 
printf£(" s\n", entry->d_name) ; 


closedir (dir); 
} 
} 


Output: 


contents of root: 


OSYS.LIB 
QDLS 
QOpensys 
QOPT 
home 
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readdir_r()--Read Directory Entry 


Syntax 


#include <sys/types.h> 
#include <dirent.h> 


int readdir_r(DIR *dirp, struct dirent *entry, 
struct dirent **result); 


Threadsafe: Conditional; see Usage Notes. 


The readdir_r() function initializes the dirent structure that is referenced by entry to represent the next 
directory entry in the directory stream that is associated with dirp. The readdir_r() function then stores a 
pointer to the entry structure at the location referenced by result. 

The storage pointed to by entry must be large enough for a dirent structure. 


If the call to readdir_r() actually reads the directory, the access time of the directory is updated. 


The readdir_r() function performs translation, if necessary, to convert the directory entry name into the 
coded character set identifier (CCSID) of the job at the time of the call to opendir(). 


Parameters 


dirp 
(Input) A pointer to a DIR that refers to the open directory stream to be read. This pointer is 


returned by opendir() (see opendir()--Open Directory). 


See QlgReaddirQ--Read Directory Entry for a description and an example of supplying the dirp in 
any CCSID. 


entry 
(Output) A pointer to a dirent structure in which the directory entry is to be placed. 
result 


(Output) A pointer to a pointer to a dirent structure. Upon successfully reading a directory entry, 
this dirent pointer is set to the same value as entry. Upon reaching the end of the directory stream, 
this pointer will be set to NULL. 


A dirent structure has the following contents: 


char d_reserved1[16] Reserved. 

unsigned int d_fileno_gen_id The generation ID associated with the file ID. 

ino_t d_fileno The file ID of the file. This number uniquely identifies the 
object within a file system. 

unsigned int d_reclen The length of the directory entry in bytes. 

int d_reserved3 Reserved. 


char d_reserved4[6] Reserved. 


char d_reserved5[2] Reserved. 


qlg_nls_t d_nlsinfo National language information about d_name. The following 
fields are defined: 


int ccsid 
CCSID of the characters in the d_name field. 
char country_id[2] 


Country or region identifier that is associated with the 
d_name field. 


char language_id[3] 


Language identifier that is associated with the d_name 
field. 


char nls_reserved[3] 


Reserved. 
unsigned int d_namelen The length of the name in bytes, excluding the null terminator. 
char d_name[640] A string that gives the name of a file in the directory. This 


string ends in a terminating null, and has a maximum length of 
{NAME_MAX} bytes, not including the terminating NULL 
(see pathconf()--Get Configurable Path Name Variables). 


Authorities 


No authorization is required. Authorization is verified during opendir(). 


Return Value 


0 
readdir_r() was successful. The result parameter points to one of the following: 
o A pointer to a dirent structure that describes the next directory entry in the directory stream. 
This will be the same value as the entry parameter. 
o A NULL pointer. readdir_r() reached the end of the directory stream. The errno global 
variable is not changed. 
error code 


readdir_r() was not successful. This value is set to the same value as the errno global variable. 


Error Conditions 


If readdir_r() is not successful, errno usually indicates one of the following errors. Under some conditions, 
errno could indicate an error other than those listed here. 


[EACCES] 


Permission denied. 


An attempt was made to access an object in a way forbidden by its object access permissions. 


The thread does not have access to the specified file, directory, component, or path. 

If you are accessing a remote file through the Network File System, update operations to file 
permissions at the server are not reflected at the client until updates to data that is stored locally by 
the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) 
command determine the time between refresh operations of local data.) Access to a remote file may 


also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote 
systems. 


[EAGAIN] 


Operation would have caused the process to be suspended. 
[EBADFID] 

A file ID could not be assigned when linking an object to a directory. 

The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as possible. 


[EBADF] 


Descriptor not valid. 


A file descriptor argument was out of range, referred to a file that was not open, or a read or write 
request was made to a file that is not open for that operation. 


A given file descriptor or directory pointer is not valid for this operation. The specified descriptor is 


incorrect, or does not refer to an open file. 


[EBUSY] 


Resource busy. 


An attempt was made to use a system resource that is not available at this time. 


[EDAMAGE] 


A damaged object was encountered. 


A referenced object is damaged. The object cannot be used. 


[EFAULT] 


The address used for an argument is not correct. 
In attempting to use an argument in a call, the system detected an address that is not valid. 
While attempting to access a parameter passed to this function, the system detected an address that 


is not valid. 


[EINVAL] 


The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on an object and 
the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. 


[EIO] 
Input/output error. 
A physical I/O error occurred. 
A referenced object may be damaged. 
[ENOSPC] 
No space available. 
The requested operations required additional space on the device and there is no space left. This 
could also be caused by exceeding the user profile storage limit when creating or transferring 
ownership of an object. 
Insufficient space remains to hold the intended file, directory, or link. 
[ENOTAVAIL] 
Independent Auxiliary Storage Pool (ASP) is not available. 
The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage (RCLSTG) 
processing. 
To recover from this error, wait until processing has completed for the independent ASP. 
[ENOTSAFE] 
Function is not allowed in a job that is running with multiple threads. 
[ESTALE] 
File or object handle rejected by server. 
If you are accessing a remote file through the Network File System, the file may have been deleted 
at the server. 
[EUNKNOWN] 


Unknown system state. 


The operation failed because of an unknown system state. See any messages in the job log and 
correct any errors that are indicated, then retry the operation. 


If interaction with a file server is required to access the object, errno could indicate one of the following 
errors: 
[EADDRNOTAVAIL] 
Address not available. 
[ECONNABORTED] 


Connection ended abnormally. 


[ECONNREFUSED] 

The destination socket refused an attempted connect operation. 
[ECONNRESET] 

A connection with a remote socket was reset by that socket. 
[EHOSTDOWN] 

A remote host is not available. 
[EHOSTUNREACH] 

A route to the remote host is not available. 
[ENETDOWN] 

The network is not currently available. 
[ENETRESET] 

A socket is connected to a host that is no longer available. 
[ENETUNREACH] 

Cannot reach the destination network. 
[ESTALE] 


File or object handle rejected by server. 
If you are accessing a remote file through the Network File System, the file may have been deleted 
at the server. 
[ETIMEDOUT] 
A remote host did not respond within the timeout period. 
[EUNATCH] 


The protocol required to support the specified address family is not available at this time. 


Error Messages 


The following messages may be sent from this function: 


CPE3418 E Possible APAR condition or hardware failure. 

CPFAOD4E _ File system error occurred. Error number &1. 

CPF3CF2 E Error(s) occurred during running of &1 API. 

CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 
1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 
Oo Where multiple threads exist in the job. 


o The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


= Root 

m QOpenSys 

m User-defined 

gw QNTC 

mg QSYS.LIB 

m =Independent ASP QSYS.LIB & 
gw QOPT 


2. readdir_r() is threadsafe only when directed to a directory in a threadsafe file system. 


3. If the dirp argument that is passed to readdir_r() does not refer to an open directory stream, 
readdir_r() returns the [EBADF] error. 


4. readdir_r() caches multiple directory entries to improve performance. This means the directory is 
not actually read on each call to readdir_r(). As a result, files that are added to the directory after 
opendir() or rewinddir() may not be returned on calls to readdir_r(Q), and files that are removed 
may still be returned on calls to readdir_r(). 


5. readdir_r() also returns directory entries for dot (.) and dot-dot (..) subdirectories. 
6. QSYS.LIB #*and Independent ASP QSYS.LIB *&File System Differences 


Calls to readdir_r() that update the access time of the directory use the normal rules that apply to 
libraries and database files. At most, the access time is updated once per day. 
7. QDLS File System Differences 


The access time of the directory is updated on opendir(). The access time is not affected by 
readdir_r(). 


When objects in QDLS are accessed, the country or region ID and language ID of the directory 
entry name are always set to the country or region ID and language ID of the system. 


When a readdir_r() operation specifies the /QDLS directory, the user must have *USE authority to 
each object in the /QDLS directory (that is, *USE authority to each object immediately below 
QDLS in the directory hierarchy). A directory entry is returned only for those objects for which the 
user has *USE authority. If the readdir_r() operation specifies a directory below QDLS, a 
directory entry is returned for all objects, even if the user does not have *USE authority for some of 
the objects. 

8. QOPT File System Differences 


The access time of the directory is not updated on a readdir_r() operation. 


Related Information 


e The <sys/types.h> file (see Header Files for UNIX-Type Functions) > 


e The <dirent.h> file (see Header Files for UNIX-Type Functions) 


@ opendir()--Open Directory 


e QlgReaddir()--Read Directory Entry 


e readdir_r_ts64(--Read Directory Entry 
@ rewinddir()--Reset Directory Stream to Beginning 


e closedir(--Close Directory 


e pathconf()--Get Configurable Path Name Variables 


Example 


The following example reads the contents of a root directory: 


#include <sys/types.h> 
#include <dirent.h> 
#include <errno.h> 
#include <stdio.h> 


main() { 
int return_code; 
DIR *dir; 
struct dirent entry; 
struct dirent *result; 


if ((dir = opendir("/")) == NULL) 
perror ("opendir() error"); 
else { 
puts ("contents of root:"); 
for (return_code = readdir_r(dir, éentry, 
result != NULL && return_code == 0; 
return_code = readdir_r(dir, &entry, 
printf£(" s\n", entry.d_name) ; 
if (return_code != 0) 
perror ("readdir_r() error"); 


closedir (dir); 
} 
} 


Output: 


contents of root: 


OSYS.LIB 
QDLS 
QOpensys 
QOPT 
home 
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&result); 


&result) ) 


readdir_r_ts64()--Read Directory Entry 


Syntax 


#include <sys/types.h> 
#include <dirent.h> 


int readdir_r_ts64(DIR * __ptré6é4 dirp, 
struct dirent * __ptr64 entry, 
struct dirent * _ ptr64 * __ptr6é4 result); 


Service Program Name: QPOLLIBTS 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The readdir_r_ts64() function initializes the dirent structure that is referenced by entry to represent the 
next directory entry in the directory stream that is associated with dirp. readdir_r_ts64() differs from 
readdir_r() in that it accepts 8-byte process local pointers. 


For a discussion of the parameters, authorities required, return values, related information, usage notes, and 
an example for the readdir_r() API, see readdir_r()--Read Directory Entry. 
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readlink()--Read Value of Symbolic Link 


Syntax 


#include <unistd.h> 


int readlink(const char *path, char *buf, size_t bufsiz); 


Threadsafe: Conditional; see Usage Notes. 


The readlink() function places the contents of the symbolic link path in the buffer buf. The size of the 
buffer is set by bufsiz. The contents of the returned buffer do not include a terminating NULL. When bufsiz 
is 0, the number of bytes contained in the symbolic link is returned and the buffer is unchanged. 


If the buffer is too small to contain the contents of the symbolic link, the contents are truncated to the size 
of the buffer (bufsiz). 


A successful readlink(), where bufsiz is greater than zero, sets the access time of the symbolic link. 


Parameters 


path 
(Input) A pointer to the null-terminated path name of the symbolic link. 
This parameter is assumed to be represented in the CCSID (coded character set identifier) currently 
in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented 
in the default CCSID of the job. 


See QlgReadlinkQ--Read Value of Symbolic Link for a description and an example of supplying 


the path in any CCSID. 
buf 
(Output) A pointer to the area in which the contents of the link should be stored. 
This parameter will be returned in the CCSID currently in effect for the job. If the CCSID of the 
job is 65535, this parameter is assumed to be represented in the default CCSID of the job. 
bufsiz 
(Input) The size of buf in bytes. 
Authorities 


Note: Adopted authority is not used. 
Authorization required for readlink() 


Authority 
Object Referred to Required errno 
[Each directory in the path name preceding the object | *X EACCES 
[Object | None None 


Return Value 


value 


readlink() was successful. 


When bufsiz is greater than zero, the value returned is the number of bytes placed in the buffer. 
When bufsiz is zero, the value returned is the number of bytes contained in the symbolic link. The 


buffer is not changed. 


If the return value is equal to bufsiz, the entire contents of the symbolic link may not have been 
returned. You can determine the size of the contents of the symbolic link by using either Istat() or 
readlink() with a zero value for bufsiz. 


readlink() was not successful. The errno global variable is set to indicate the error. 


Error Conditions 


If readlink() is not successful, errno usually indicates one of the following errors. Under some conditions, 
errno could indicate an error other than those listed here. 


[EACCES] 


Permission denied. 


An attempt was made to access an object in a way forbidden by its object access permissions. 
The thread does not have access to the specified file, directory, component, or path. 


If you are accessing a remote file through the Network File System, update operations to file 
permissions at the server are not reflected at the client until updates to data that is stored locally by 
the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) 
command determine the time between refresh operations of local data.) Access to a remote file may 
also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote 
systems. 


[EAGAIN] 
Operation would have caused the process to be suspended. 


[EBADFID] 
A file ID could not be assigned when linking an object to a directory. 


The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as possible. 


[EBADNAME] 


The object name specified is not correct. 
[EBUSY] 
Resource busy. 


An attempt was made to use a system resource that is not available at this time. 


[ECONVERT] 


Conversion error. 


One or more characters could not be converted from the source CCSID to the target CCSID. 


[EDAMAGE] 


A damaged object was encountered. 


A referenced object is damaged. The object cannot be used. 


[EFAULT] 


The address used for an argument is not correct. 
In attempting to use an argument in a call, the system detected an address that is not valid. 
While attempting to access a parameter passed to this function, the system detected an address that 


is not valid. 


[EFILECVT] 


File ID conversion of a directory failed. 


Try to run the Reclaim Storage (RCLSTG) command to recover from this error. 


[EINTR] 


Interrupted function call. 
[EINVAL] 
The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on an object and 
the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. 


The named file is not a symbolic link. 


[EIO] 


Input/output error. 


A physical I/O error occurred. 


A referenced object may be damaged. 


[EISDIR] 


Specified target is a directory. 
The path specified named a directory where a file or object name was expected. 


The path name given is a directory. 


[ELOOP] 
A loop exists in the symbolic links. 
This error is issued if the number of symbolic links encountered is more than POSIX_SYMLOOP 


(defined in the limits.h header file). Symbolic links are encountered during resolution of the 
directory or path name. 


[ENAMETOOLONG] 
A path name is too long. 
A path name is longer than PATH_MAX characters or some component of the name is longer than 
NAME_MAX characters while _POSIX_NO_TRUNC is in effect. For symbolic links, the length 


of the name string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and 
NAME_MAxX values can be determined using the pathconf() function. 


[ENOENT] 
No such path or directory. 


The directory or a component of the path name specified does not exist. 


A named file or directory does not exist or is an empty string. 


[ENOMEM] 


Storage allocation request failed. 
A function needed to allocate storage, but no storage is available. 


There is not enough memory to perform the requested function. 


[ENOSPC] 
No space available. 
The requested operations required additional space on the device and there is no space left. This 
could also be caused by exceeding the user profile storage limit when creating or transferring 
ownership of an object. 


Insufficient space remains to hold the intended file, directory, or link. 


[ENOTAVAIL] 
Independent Auxiliary Storage Pool (ASP) is not available. 


The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage (RCLSTG) 
processing. 


To recover from this error, wait until processing has completed for the independent ASP. 


[ENOTDIR] 


Not a directory. 


A component of the specified path name existed, but it was not a directory when a directory was 
expected. 


Some component of the path name is not a directory, or is an empty string. 


[ENOTSAFE] 


Function is not allowed in a job that is running with multiple threads. 


[ENOTSUP] 


Operation not supported. 


The operation, though supported in general, is not supported for the requested object or the 
requested arguments. 


[EROOBJ] 
Object is read only. 


You have attempted to update an object that can be read only. 


[ESTALE] 
File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may have been deleted 
at the server. 


[EUNKNOWN] 
Unknown system state. 


The operation failed because of an unknown system state. See any messages in the job log and 
correct any errors that are indicated, then retry the operation. 


If interaction with a file server is required to access the object, errno could indicate one of the following 
errors: 
[EADDRNOTAVAIL] 
Address not available. 
[ECONNABORTED] 


Connection ended abnormally. 


[ECONNREFUSED] 


The destination socket refused an attempted connect operation. 


[ECONNRESET] 

A connection with a remote socket was reset by that socket. 
[EHOSTDOWN] 

A remote host is not available. 
[EHOSTUNREACH] 

A route to the remote host is not available. 
[ENETDOWN] 

The network is not currently available. 
[ENETRESET] 

A socket is connected to a host that is no longer available. 
[ENETUNREACH] 

Cannot reach the destination network. 
[ESTALE] 


File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may have been deleted 
at the server. 

[ETIMEDOUT] 
A remote host did not respond within the timeout period. 

[EUNATCH] 


The protocol required to support the specified address family is not available at this time. 


Error Messages 


The following messages may be sent from this function: 


CPE3418 E Possible APAR condition or hardware failure. 

CPFAOD4E _ File system error occurred. Error number &1. 

CPF3CF2 E Error(s) occurred during running of &1 API. 

CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 
1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 
o Where multiple threads exist in the job. 
oO. The object on which this function is operating resides in a file system that is not threadsafe. 


Only the following file systems are threadsafe for this function: 


m Root 


m QOpenSys 

m User-defined 

wg QNTC 

a QSYS.LIB 

m “Independent ASP QSYS.LIB 
gw QOPT 


2. File System Differences 


The following file systems do not support readlink(). 
o QSYS.LIB 
o Independent ASP QSYS.LIB 
o QDLS 
Oo QOPT 
Oo QNetWare 
Oo QNTC 


Related Information 


e The <unistd.h> file (see Header Files for UNIX-Type Functions) 


e IstatQ--Get File or Link Information 

e@ QlgReadlink(Q)--Read Value of Symbolic Link 
e stat()--Get File Information 

e symlinkQ--Make Symbolic Link 


e@ unlink()--Remove Link to File 


Example 


The following example uses readlink(): 


#include <unistd.h> 
#include <sys/types.h> 
#include <sys/stat.h> 
#include <fcntl.h> 


main() { 
char fn[]="readlink.file"; 
char sl[]="readlink.symlink"; 


char buf[30]; 
int file_descriptor; 


if ((file_descriptor = creat(fn, S_IWUSR)) < 0) 
perror("creat() error"); 


else { 
close(file_descriptor) ; 


if (symlink(fn, sl) != 0) 
perror ("symlink() error"); 
else { 


if (readlink(sl, buf, sizeof(buf)) < 0) 
perror ("readlink() error"); 
else printf("readlink() returned '%s' for '%s'\n", buf, sl); 
unlink(sl)j; 
} 


unlink (fn); 


} 
Output: 


readlink() returned 'readlink.file' for 'readlink.symlink' 
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readv()--Read from Descriptor Using Multiple 
Buffers 


Syntax 


#include <sys/types.h> 
#include <sys/uio.h> 


int readv(int descriptor, 
struct iovec *io_vector[], 
int vector_length) 


Threadsafe: Conditional; see Usage Notes. 


The readv() function is used to receive data from a file or socket descriptor. readv() provides a way for data 
to be stored in several different buffers (scatter/gather I/O). 


See read()--Read from Descriptor for more information related to reading from a descriptor. 


Parameters 


descriptor 


(Input) The descriptor to be read. The descriptor refers to a file or a socket. 


io_vector[] 


(I/O) The pointer to an array of type struct iovec. struct iovec contains a sequence of pointers to 
buffers in which the data to be read is stored. The structure pointed to by the io_vector parameter is 
defined in <sys/uio.h>. 


struct iovec { 
void *iov_base; 
size_t iov_len; 


} 


iov_base and iov_len are the only fields in iovec used by sockets. iov_base contains the pointer to a 
buffer and iov_len contains the buffer length. The rest of the fields are reserved. 


vector_length 


(Input) The number of entries in io_vector. 


Authorities 


No authorization is required. 


Return Value 


readv() returns an integer. Possible values are: 


e -! (unsuccessful) 


e n (successful), where n is the number of bytes read. 


Error Conditions 


If readv() is not successful, errno usually indicates one of the following errors. Under some conditions, 
errno could indicate an error other than those listed here. 


[EACCES] 


[EAGAIN] 


[EBADF] 


[EBADFID] 


[EBUSY] 


Permission denied. 


An attempt was made to access an object in a way forbidden by its object access 
permissions. 


The thread does not have access to the specified file, directory, component, or path. 


If you are accessing a remote file through the Network File System, update operations 
to file permissions at the server are not reflected at the client until updates to data that 
is stored locally by the Network File System take place. (Several options on the Add 
Mounted File System (ADDMFS) command determine the time between refresh 
operations of local data.) Access to a remote file may also fail due to different 
mappings of user IDs (UID) or group IDs (GID) on the local and remote systems. 


This may occur if file_descriptor refers to a socket and the socket is using a 
connection-oriented transport service, and a connect() was previously completed. The 
thread, however, does not have the appropriate privileges to the objects that were 
needed to establish a connection. For example, the connect() required the use of an 
APPC device that the thread was not authorized to. 


Operation would have caused the process to be suspended. 


Descriptor not valid. 


A file descriptor argument was out of range, referred to a file that was not open, or a 
read or write request was made to a file that is not open for that operation. 


A given file descriptor or directory pointer is not valid for this operation. The 
specified descriptor is incorrect, or does not refer to an open file. Or, this readv 
request was made to a file that was only open for writing. 

A file ID could not be assigned when linking an object to a directory. 


The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as 
possible. 


Resource busy. 


An attempt was made to use a system resource that is not available at this time. 


[EDAMAGE] A damaged object was encountered. 
A referenced object is damaged. The object cannot be used. 
[EFAULT] The address used for an argument is not correct. 


In attempting to use an argument in a call, the system detected an address that is not 
valid. 


While attempting to access a parameter passed to this function, the system detected an 
address that is not valid. 


(EINTR] Interrupted function call.*& 


[EINVAL] The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on 
an object and the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. 


This may occur if file_descriptor refers to a socket that is using a connectionless 
transport service, is not a socket of type SOCK_RAW, and is not bound to an address. 


The file resides in a file system that does not support large files, and the starting 
offset of the file exceeds 2 GB minus 2 bytes. 


[EIO] Input/output error. 
A physical I/O error occurred. 
A referenced object may be damaged. 
[ENOMEM] Storage allocation request failed. 
A function needed to allocate storage, but no storage is available. 
There is not enough memory to perform the requested function. 
[ENOTAVAIL] Independent Auxiliary Storage Pool (ASP) is not available. 


The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage 
(RCLSTG) processing. 


To recover from this error, wait until processing has completed for the independent 
ASP. 


[ENOTSAFE] Function is not allowed in a job that is running with multiple threads. 


[EOVERFLOW] Object is too large to process. 
The object's data size exceeds the limit allowed by this function. 


The file is a regular file, nbyte is greater than 0, the starting offset is before the 
end-of-file and is greater than or equal to 2GB minus 2 bytes. 


2}[ERESTART] A system call was interrupted and may be restarted.*& 


[ESTALE] File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may have 
been deleted at the server. 


[EUNKNOWN] Unknown system state. 


The operation failed because of an unknown system state. See any messages in the 
job log and correct any errors that are indicated, then retry the operation. 


When the descriptor refers to a socket, errno could indicate one of the following errors: 


[ECONNABORTED] 


[ECONNREFUSED] 


[ECONNRESET] 


[EINTR] 


[ENOTCONN] 


[ETIMEDOUT] 


[EUNATCH] 


[EWOULDBLOCK] 


Connection ended abnormally. 


This error code indicates that the transport provider ended the connection 
abnormally because of one of the following: 


e The retransmission limit has been reached for data that was being sent on 
the socket. 


e A protocol error was detected. 


The destination socket refused an attempted connect operation. 


A connection with a remote socket was reset by that socket. 


Interrupted function call. 


Requested operation requires a connection. 


This error code is returned only on sockets that use a connection-oriented 
transport service. 


A remote host did not respond within the timeout period. 


A non-blocking connect() was previously completed that resulted in the 
connection timing out. No connection is established. This error code is returned 
only on sockets that use a connection-oriented transport service. 


The protocol required to support the specified address family is not available at 
this time. 


Operation would have caused the process to be suspended. 


If interaction with a file server is required to access the object, errno could indicate one of the following 


errors: 


[EADDRNOTAVAIL] Address not available. 


[ECONNABORTED] 


Connection ended abnormally. 


[ECONNREFUSED] 


[ECONNRESET] 


[EHOSTDOWN] 


[EHOSTUNREACH] 


[ENETDOWN] 


[ENETRESET] 


[ENETUNREACH] 


[ESTALE] 


[ETIMEDOUT] 


[EUNATCH] 


Error Messages 


The destination socket refused an attempted connect operation. 

A connection with a remote socket was reset by that socket. 

A remote host is not available. 

A route to the remote host is not available. 

The network is not currently available. 

A socket is connected to a host that is no longer available. 

Cannot reach the destination network. 

File or object handle rejected by server. 

If you are accessing a remote file through the Network File System, the file may 
have been deleted at the server. 


A remote host did not respond within the timeout period. 


The protocol required to support the specified address family is not available at 
this time. 


Message ID Error Message Text 


CPE3418 E Possible APAR condition or hardware failure. 


CPF3CF2 E Error(s) occurred during running of &1 API. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFAO081 E Unable to set return value or error code. 


CPFA0D4 E File system error occurred. Error number &1. 


Usage Notes 
1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 


oO Where multiple threads exist in the job. 


o The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


m Root 

m QOpenSys 

m User-defined 

gw QNTC 

mg QSYS.LIB 

m Independent ASP QSYS.LIB & 
mw QOPT 


2. The io_vector[] parameter is an array of struct iovec structures. When a readv() is issued, the 
system processes the array elements one at a time, starting with io_vector[0]. For each element, 
iov_len bytes of received data are placed in storage pointed to by iov_base. Data is placed in 
storage until all buffers are full, or until there is no more data to receive. Only the storage pointed 
to by iov_base is updated. No change is made to the iov_len fields. To determine the end of the 
data, the application program must use the following: 


o The function return value (the total number of bytes received). 


oO The lengths of the buffers pointed to by iov_base. 


3. For sockets that use a connection-oriented transport service (for example, sockets with a type of 
SOCK_STREAM), a returned value of zero indicates one of the following: 


o The partner program has issued a close() for the socket. 
oO The partner program has issued a shutdown() to disable writing to the socket. 
o The connection is broken and the error was returned on a previously issued socket function. 


oO A shutdown() to disable reading was previously done on the socket. 


4. The following applies to sockets that use a connectionless transport service (for example, a socket 
with a type of SOCK_DGRAM): 


oO If aconnect() has been issued previously, then data can be received only from the address 
specified in the previous connect(). 


o The address from which data is received is discarded, because the readv() has no address 
parameter. 


o The entire message must be read in a single read operation. If the size of the message is too 
large to fit in the user-supplied buffers, the remaining bytes of the message are discarded. 


o Areturned value of zero indicates one of the following: 
m The partner program has sent a NULL message (a datagram with no user data). 


a A shutdown() to disable reading was previously done on the socket. 


m The buffer length specified by the application was zero. 


5. For the file systems that do not support large files, readv() will return [EINVAL] if the starting 
offset exceeds 2GB minus 2 bytes, regardless of how the file was opened. For the file systems that 
do support large files, readv() will return [EOVERFLOW] if the starting offset exceeds 2GB minus 
2 bytes and file was not opened for large file access. 


6. QFileSvr.400 File System Differences 


The largest buffer size allowed is 16 megabytes. If a larger buffer is passed, the error EINVAL will 
be received. 

7. QOPT File System Differences 
When reading from files on volumes formatted in Universal Disk Format (UDF), byte locks on the 
range being read are ignored. 


8. Using this function successfully on the /dev/null #*or /dev/zero *&character special file results in a 
return value of 0. In addition, the access time for the file is updated. 


Related Information 


e The <limits.h> file (see Header Files for UNIX-Type Functions) 
e The <unistd.h> file (see Header Files for UNIX-Type Functions) 


@ creat()--Create or Rewrite File 


e dup(--Duplicate Open File Descriptor 


e@ dup2()--Duplicate Open File Descriptor to Another Descriptor 


e fcntl0--Perform File Control Command 


e ioctl(--Perform I/O Control Request 
@ lseek()--Set File Read/Write Offset 


@ open()--Open File 


e@ read()--Read from Descriptor 


@ recv()--Receive Data 


e recvfrom(--Receive Data 
e@ recvmsg()--Receive Data or Descriptors or Both 


@ write(--Write to Descriptor 


@ writev()--Write to Descriptor Using Multiple Buffers 
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rename()--Rename File or Directory 


Syntax 


#include <Qp0lstdi.h> 


int rename (const char *old, const char *new); 


Threadsafe: Conditional; see Usage Notes. 


The rename() function can be defined to be either Qp0IRenameUnlink() or Qp0IRenameKeep(), 
depending upon the definitions of the _POSIX_SOURCE and _POSIX1_SOURCE macros in the 
<Qp0lstdi.h> header file: 


@ When POSIX SOURCE or _POSIX1_ SOURCE is defined, rename() is defined to be 
Qp0IRenameUnlink(). Either rename() or Qp0IRenameUnlink() can be used to rename a file or 
directory with the semantics of Qp0IRenameUnlink(). 


e When _POSIX_SOURCE and _POSIX1_SOURCE are not defined, rename() is defined to be 
Qp0IRenameKeep(). Either rename() or Qp0IRenameKeep() can be used to rename a file or 
directory with the semantics of Qp0IRenameKeep(). 


When the <Qp0lIstdi.h> header file is not included, rename() operates only on database files in the 
QSYS.LIB #*or independent ASP QSYS.LIB “file system, as it did before the introduction of the 
integrated file system. 


For details on the use of rename(), see the Qp0IRenameUnlink() and Qp0IRenameKeep() functions. 


Parameters 


old 
(Input) A pointer to the null-terminated path name of the file to be renamed. 
This parameter is assumed to be represented in the CCSID (coded character set identifier) currently 


in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented 
in the default CCSID of the job. 


new 
(Input) A pointer to the null-terminated path name of the new name of the file. 
This parameter is assumed to be represented in the CCSID currently in effect for the job. If the 


CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the 
job. 


The new file name is assumed to be represented in the language and country or region currently in 
effect for the process. 


Usage Notes 


1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 
oO Where multiple threads exist in the job. 


o The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


m Root 

m QOpenSys 

m User-defined 

gw QNTC 

mw QSYS.LIB 

m 2Independent ASP QSYS.LIB & 
gw QOPT 


Related Information 


e The <stdio.h> file (see Header Files for UNIX-Type Functions) 

e@ The <QpOlstdi.h> file (see Header Files for UNIX-Type Functions) 

e@ pathconf()--Get Configurable Path Name Variables 

e@ Qp0lRenameKeep()--Rename File or Directory, Keep "new" If It Exists 

e@ Qp0lRenameUnlinkQ--Rename File or Directory, Unlink "new" If It Exists 
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rewinddir()--Reset Directory Stream to 
Beginning 


Syntax 


#include <sys/types.h> 
#include <dirent.h> 


void rewinddir(DIR *dirp); 
Threadsafe: Yes 


The rewinddir() function "rewinds" the position of an open directory stream to the beginning. dirp points 
to a DIR associated with an open directory stream. 


The next call to readdir() reads the first entry in the directory. If the contents of the directory have changed 
since the directory was opened and rewinddir() is called, subsequent calls to readdir() read the changed 
contents. 


Parameters 


dirp 
(Input) A pointer to a DIR that refers to the open directory stream to be rewound. This pointer is 
returned by the opendir() function. 


Authorities 


No authorization is required. Authorization is verified during opendir(). 


Return Value 


None. 


Error Conditions 


None. 


Error Messages 


The following messages may be sent from this function: 
CPE3418 E 

Possible APAR condition or hardware failure. 
CPFIFO05 E 

Directory handle not valid. 
CPF3CF2 E 


Error(s) occurred during running of &1 API. 


Usage Notes 


1. If the dirp argument passed to rewinddir() does not refer to an open directory, unexpected results 
could occur. 


2. Files that are added to the directory after opendir() or rewinddir() may not be returned on calls to 
readdir(). 


Related Information 


e The <sys/types.h> file (see Header Files for UNIX-Type Functions) 


e The <dirent.h> file (see Header Files for UNIX-Type Functions) 
@ opendir(--Open Directory 


e readdir()--Read Directory Entry 


e closedirQ--Close Directory 


Example 


The following example produces the contents of a directory by opening it, rewinding it, and closing it: 


#include <sys/types.h> 
#include <dirent.h> 
#include <errno.h> 
#include <stdio.h> 


main() { 
DIR *dir; 
struct dirent *entry; 


if ((dir = opendir("/")) == NULL) 
perror ("opendir() error"); 
else { 


puts ("contents of root:"); 
while ((entry = readdir(dir)) != NULL) 


printf("Ss ", entry->d_name) ; 
rewinddir(dir); 
puts (" ") ; 
while ((entry = readdir(dir)) != NULL) 
printf("Ss ", entry-—>d_name) ; 
closedir(dir); 
puts (""); 


} 
Output: 


contents of root: 
QSYS.LIB QDLS QOpenSys QOPT home 
QSYS.LIB QDLS QOpenSys QOPT home newdir 
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rmdir()--Remove Directory 


Syntax 


#include <unistd.h> 


int rmdir(const char *path); 


Threadsafe: Conditional; see Usage Notes. 


The rmdir() function removes a directory, path, provided that the directory is empty; that is, the directory 
contains no entries other than "dot" (.) or "dot-dot" (..). path must not end in dot (.) or dot-dot (..). 


If no job currently has the directory open, rmdir() deletes the directory itself. The space occupied by the 
directory is freed for new use. If one or more jobs have the directory open, rmdir() removes the link and 
the dot (.) or dot-dot (..). entries. The directory itself is not removed until the last job closes the directory. 
New files cannot be created under a directory after the last link is removed, even if the directory is still 
open. 


rmdir() does not remove a directory that still contains files or subdirectories. If path refers to a directory 
that is not empty, the [ENOTEMPTY] error is returned. If path refers to the current directory of the current 
job, to the root (/) directory, or to a directory that cannot be removed, the [EBUSY] error is returned. 


If path refers to a symbolic link, rmdir() does not affect any file or directory named by the contents of the 
symbolic link. 


If rmdir() is successful, the change and modification times for the parent directory are updated. 


Parameters 


path 
(Input) A pointer to the null-terminated path name of the directory to be removed. 
This parameter is assumed to be represented in the CCSID (coded character set identifier) currently 


in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented 
in the default CCSID of the job. 


See QlgRmdir()--Remove Directory (using NLS-enabled path name) for a description and an 
example of supplying the path in any CCSID. 


Authorities 


Note: Adopted authority is not used. 


Figure 1-70. Authorization Required for rmdir() (excluding QSYS.LIB, independent ASP 
QSYS.LIB, “and QDLS) 


Authority 
Object Referred to Required errno 


[Each directory in the path name preceding the directory to be removed [FX [EACCES 
[Parent directory of the directory to be removed [*WX |EACCES 
[Directory to be removed |*OBJEXIST [EACCES 


Figure 1-71. Authorization Required for rmdir() in the QSYS.LIB “and independent ASP 
QSYS.LIB File Systems** 


Authority 
Object Referred to Required [errno 
[Each directory in the path name preceding the directory to be removed [*x [EACCES 
[Parent directory of the directory to be removed [*x [EACCES 


Directory to be removed, if it is a library *OBJEXIST, |EACCES 
*RX 

Directory to be removed, if it is a database file *OBJEXIST, |EACCES 
*OBJOPR 


Figure 1-72. Authorization Required for rmdir() in the QDLS File System 


Authority 
Object Referred to Required __ errno 
[Each directory in the path name preceding the directory to be removed [*x [EACCES 
[Parent directory of the directory to be removed [*X [EACCES 


Directory to be removed *OBJEXIST, |EACCES 
| is | 
Figure 1-73. Authorization Required for rmdir() in the QOPT File System 


Authority 
Object Referred to Required errno 


[Volume authorization list [CHAN GE [EACCES 
Each directory in the path name preceding the directory to be removed if volume EACCES 
media format is Universal Disk Format (UDF) 

Parent directory of the directory to be removed if volume media format is EACCES 
Universal Disk Format (UDF) 


[Directory to be removed if volume media format is Universal Disk Format (UDF) [*W [EACCES 


Directory and parent directories if volume media format is not Universal Disk None None 
Format (UDF) 


Return Value 


0) 
rmdir() was successful. 
-l 


rmdir() was not successful. The errno global variable is set to indicate the error. 


Error Conditions 


If rmdir( is not successful, errno usually indicates one of the following errors. Under some conditions, 
errno could indicate an error other than those listed here. 


[EACCES] 
Permission denied. 
An attempt was made to access an object in a way forbidden by its object access permissions. 
The thread does not have access to the specified file, directory, component, or path. 
If you are accessing a remote file through the Network File System, update operations to file 
permissions at the server are not reflected at the client until updates to data that is stored locally by 
the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) 
command determine the time between refresh operations of local data.) Access to a remote file may 


also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote 
systems. 


[EAGAIN] 


Operation would have caused the process to be suspended. 
[EBADFID] 

A file ID could not be assigned when linking an object to a directory. 

The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as possible. 


[EBADNAME] 


The object name specified is not correct. 
[EBUSY] 
Resource busy. 
An attempt was made to use a system resource that is not available at this time. 
The path cannot be removed because it is the current working directory of the current process, or it 


is currently being used by the system. 


[ECONVERT] 


Conversion error. 


One or more characters could not be converted from the source CCSID to the target CCSID. 


[EDAMAGE] 


A damaged object was encountered. 


A referenced object is damaged. The object cannot be used. 


[EFAULT] 


The address used for an argument is not correct. 
In attempting to use an argument in a call, the system detected an address that is not valid. 
While attempting to access a parameter passed to this function, the system detected an address that 


is not valid. 


[EFILECVT] 


File ID conversion of a directory failed. 


Try to run the Reclaim Storage (RCLSTG) command to recover from this error. 


[EINTR] 


Interrupted function call. 
[EINVAL] 
The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on an object and 
the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. The last component of path is 'dot' or 


‘dot-dot'. 


[EIO] 


Input/output error. 
A physical I/O error occurred. 


A referenced object may be damaged. 


#[EJRNDAMAGE] 
Journal damaged. 
A journal or all of the journal's attached journal receivers are damaged, or the journal sequence 


number has exceeded the maximum value allowed. This error occurs during operations that were 
attempting to send an entry to the journal. 


[EJRNENTTOOLONG] 
Entry too large to send. 


The journal entry generated by this operation is too large to send to the journal. 


[EJRNINACTIVE] 


Journal inactive. 


The journaling state for the journal is *INACTIVE. This error occurs during operations that were 
attempting to send an entry to the journal. 


[EJRNRCVSPC] 


Journal space or system storage error. 


The attached journal receiver does not have space for the entry because the storage limit has been 
exceeded for the system, the object, the user profile, or the group profile. This error occurs during 
operations that were attempting to send an entry to the journal.*& 


[ELOOP] 


A loop exists in the symbolic links. 


This error is issued if the number of symbolic links encountered is more than POSIX_S YMLOOP 
(defined in the limits.h header file). Symbolic links are encountered during resolution of the 
directory or path name. 


[ENAMETOOLONG] 


A path name is too long. 


A path name is longer than PATH_MAX characters or some component of the name is longer than 
NAME_MAX characters while _POSIX_NO_TRUNC is in effect. For symbolic links, the length 
of the name string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and 
NAME_MAX values can be determined using the pathconf() function. 


(ENEWJRN] 
New journal is needed. 
The journal was not completely created, or an attempt to delete it did not complete successfully. 


This error occurs during operations that were attempting to start or end journaling, or were 
attempting to send an entry to the journal. 


[ENEWJRNRCV] 
New journal receiver is needed. 
A new journal receiver must be attached to the journal before entries can be journaled. This error 


occurs during operations that were attempting to send an entry to the journal.*& 


[ENOENT] 
No such path or directory. 


The directory or a component of the path name specified does not exist. 


A named file or directory does not exist or is an empty string. The last component of the path name 
is dot or dot-dot. 


[ENOMEM] 


Storage allocation request failed. 
A function needed to allocate storage, but no storage is available. 


There is not enough memory to perform the requested function. 


[ENOSPC] 
No space available. 
The requested operations required additional space on the device and there is no space left. This 
could also be caused by exceeding the user profile storage limit when creating or transferring 
ownership of an object. 


Insufficient space remains to hold the intended file, directory, or link. 


[ENOTAVAIL] 
Independent Auxiliary Storage Pool (ASP) is not available. 


The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage (RCLSTG) 
processing. 


To recover from this error, wait until processing has completed for the independent ASP. 


[ENOTDIR] 


Not a directory. 


A component of the specified path name existed, but it was not a directory when a directory was 
expected. 


Some component of the path name is not a directory, or is an empty string. 


[ENOTEMPTY] 


Directory not empty. 


You tried to remove a directory that is not empty. A directory cannot contain objects when it is 
being removed. 


The specified directory is not empty. 


[ENOTSAFE] 


Function is not allowed in a job that is running with multiple threads. 


[ENOTSUP] 
Operation not supported. 
The operation, though supported in general, is not supported for the requested object or the 


requested arguments. 


[EPERM] 


Operation not permitted. 


You must have appropriate privileges or be the owner of the object or other resource to do the 
requested operation. 


[EROOBJ] 
Object is read only. 


You have attempted to update an object that can be read only. 


[EUNKNOWN] 
Unknown system state. 


The operation failed because of an unknown system state. See any messages in the job log and 
correct any errors that are indicated, then retry the operation. 


[ESTALE] 
File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may have been deleted 
at the server. 


If interaction with a file server is required to access the object, errno could indicate one of the following 
errors: 
[EADDRNOTAVAIL] 

Address not available. 
[ECONNABORTED] 

Connection ended abnormally. 
[ECONNREFUSED] 

The destination socket refused an attempted connect operation. 
[ECONNRESET] 

A connection with a remote socket was reset by that socket. 
[EHOSTDOWN] 

A remote host is not available. 
[EHOSTUNREACH] 

A route to the remote host is not available. 
[ENETDOWN] 

The network is not currently available. 
[ENETRESET] 

A socket is connected to a host that is no longer available. 
[ENETUNREACH] 

Cannot reach the destination network. 
[ESTALE] 


File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may have been deleted 
at the server. 


[ETIMEDOUT] 
A remote host did not respond within the timeout period. 
[EUNATCH] 


The protocol required to support the specified address family is not available at this time. 


Error Messages 


The following messages may be sent from this function: 
CPE3418 E 

Possible APAR condition or hardware failure. 
CPFA0D4 E 

File system error occurred. Error number &1. 
CPF3CF2 E 

Error(s) occurred during running of &1 API. 
CPF9872 E 


Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 


1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 
oO Where multiple threads exist in the job. 


oO. The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


m Root 

m QOpenSys 

m User-defined 

wg QNTC 

mg QSYS.LIB 

m “Independent ASP QSYS.LIB & 
gw QOPT 


2. QSYS.LIB #and Independent ASP QSYS.LIB “&File System Differences 
If one or more jobs have the library or file open, rmdir() returns [EBUSY]. 


If rmdir() is successful, the change and modification times for the parent library are updated only 
if the "directory" being removed is a database file. 


3. QDLS File System Differences 


If one or more jobs have the folder open, or are using the folder as their current directory, rmdir() 
returns [EBUSY]. 


4. QOPT File System Differences 
The change and modification times of the parent directory are not updated. 


If path refers to a directory that any job has open, the [EBUSY] error is returned. 


5. QNTC File System Differences 


The change and modification times of the parent directory are not updated. 


Related Information 


e The <unistd.h> file (see Header Files for UNIX-Type Functions) 
e mkdir()--Make Directory 


e QlgRmdirQ--Remove Directory (using NLS-enabled path name) 


e unlinkQ--Remove Link to File 


Example 
The following example removes a directory: 


#include <sys/stat.h> 
#include <unistd.h> 
#include <stdio.h> 
#include <sys/stat.h> 
#include <fcntl.h> 


main() { 
char new_dir[]="new_dir"; 
char new_file[]="new_dir/new_file"; 


int file_descriptor; 


if (mkdir(new_dir, S_IRWXU|S_IRGRP|S_IXGRP) != 0) 
perror("mkdir() error"); 

else if ((file_descriptor = creat (new_file, S_IWUSR)) < 0) 
perror ("creat() error"); 

else { 


close(file_descriptor) ; 
unlink (new_file); 


} 


if (rmdir(new_dir) != 0) 
perror("rmdir() error"); 
else 
puts ("removed!"); 
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stat()--Get File Information 


Syntax 


#include <sys/stat.h> 


int stat(const char *path, struct stat *buf); 


Threadsafe: Conditional; see Usage Notes. 


The stat() function gets status information about a specified file and places it in the area of memory pointed 
to by the buf argument. 


If the named file is a symbolic link, stat() resolves the symbolic link. It also returns information about the 
resulting file. 


Parameters 


path 
(Input) A pointer to the null-terminated path name of the file from which information is required. 
This parameter is assumed to be represented in the CCSID (coded character set identifier) currently 


in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented 
in the default CCSID of the job. 


See QlgStat()--Get File Information (using NLS-enabled path name) for a description and an 
example of supplying the path in any CCSID. 


buf 


(Output) A pointer to the area to which the information should be written. 


The information is returned in the following stat structure, as defined in the <sys/stat.h> header file: 


mode_t st_mode A bit string indicating the permissions and privileges of the 
file. Symbols are defined in the <sys/stat.h> header file to refer 
to bits in a mode_t value; these symbols are listed in 
chmod()--Change File Authorizations. 


ino_t st_ino The file ID for the object. This number uniquely identifies the 
object within a file system. When st_ino and st_dev are used 
together, they uniquely identify the object on the system. 


nlink_t st_nlink The number of links to the file. #*This field will be 65,535 if 
the value could not fit in the specified nlink_t field. The 
complete value will be in the st_nlink32 field.“ 


= unsigned short —_ st_reserved2 Reserved. 


uid_t 
gid_t 


off_t 


time_t 
time_t 
time_t 


dev_t 


size_t 
unsigned long 


qpOl_objtype_t 


unsigned short 


unsigned short 


st_uid 
st_gid 


st_size 


st_atime 
st_mtime 
st_ctime 


st_dev 


st_blksize 
st_allocsize 


st_objtype 


st_codepage 


st_ccsid 


The numeric user ID (uid) of the owner of the file. 
The numeric group ID (gid) for the file. 


Defined as follows for each file type: 
Regular File 
The number of data bytes in the file. 
Directory 
The number of bytes allocated to the directory. 
Symbolic Link 


The number of bytes in the path name stored in the 
symbolic link. 


Local Socket 
Always zero. 
OS/400 Native Object 


This value is dependent on the object type. 
The most recent time the file was accessed. 


The most recent time the contents of the file were changed. 
The most recent time the status of the file was changed. 

The file system ID to which the object belongs. This number 
uniquely identifies the file system to which the object belongs. 
When st_ino and st_dev are used together, they uniquely 
identify the object on the system. #*This field will be 
4,294,967,295 if the value could not fit in the specified dev_t 
field. The complete value will be in the st_dev64 field. & 

The block size of the file in bytes. 

The number of bytes allocated to the file. 


The iSeries object type; for example, *STMEF or *DIR. Refer 


o CL Programmin Por a list of the iSeries object types. 


The code page derived from the CCSID used for the data in the 
file or the extended attributes of the directory. If the returned 
value of this field is zero (0), there is more than one code page 
associated with the st_ccsid. If the st_ccsid is not a supported 
iSeries CCSID, the st_codepage is set equal to the st_ccsid. 


The CCSID used for the data in the file or the extended 
attributes of the directory. 


= dev_t st_rdev The device ID of the object if the object is a character special 
file or block special file. This number uniquely identifies the 
file device. This field will be 4,294,967,295 if the value could 
not fit in the specified dev_t field. The complete value will be 
in the st_rdev64 field. 


= nlink32 st_nlink32 The number of links to the file.*& 

= dev64_t st_rdev64 The device ID of the object in 64 bit format. See st_rdev for 
more information.*& 

2 dev64_t st_dev64 The file system ID to which the object belongs in 64 bit 
format. See st_dev for more information.*& 

2 char st_reserved1[36] Reserved.*& 

unsigned int st_ino_gen_id The generation ID associated with the file ID. 


Values of time_t are given in terms of seconds since a fixed point in time called the Epoch. 
You can examine properties of a mode_t value from the st_mode field using a collection of macros defined 
in the <sys/stat.h> header file. If mode is a mode_t value, then: 
S_ISBLK(mode) 
Is nonzero for block special files 
S_ISCHR(mode) 
Is nonzero for character special files 
S_ISDIR(mode) 
Is nonzero for directories 
S_ISFIFO(mode) 
Is nonzero for pipes and FIFO special files 
S_ISREG(mode) 
Is nonzero for regular files 
S_ISLNK(mode) > 
Is nonzero for symbolic links 
S_ISSOCK(mode) 
Is nonzero for local sockets 
S_ISNATIVE(mode) 


Is nonzero for OS/400 native objects 


Authorities 


Note: Adopted authority is not used. 
Figure 1-74. Authorization Required for stat()> 


[Object Referred to [Authority Required [errno 
[Each directory in the path name preceding the object [*x [EACCES 


[Object [None [None 


Return Value 


O 
stat() was successful. The information is returned in buf. 
-l 


stat() was not successful. The errno global variable is set to indicate the error. 


Error Conditions 


If statQ is not successful, errno usually indicates one of the following errors. Under some conditions, errno 
could indicate an error other than those listed here. 


[EACCES] 
Permission denied. 
An attempt was made to access an object in a way forbidden by its object access permissions. 
The thread does not have access to the specified file, directory, component, or path. 
If you are accessing a remote file through the Network File System, update operations to file 
permissions at the server are not reflected at the client until updates to data that is stored locally by 
the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) 
command determine the time between refresh operations of local data.) Access to a remote file may 


also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote 
systems. 


[EAGAIN] 


Operation would have caused the process to be suspended. 
[EBADFID] 

A file ID could not be assigned when linking an object to a directory. 

The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as possible. 


[EBADNAME] 


The object name specified is not correct. 


[EBUSY] 


Resource busy. 


An attempt was made to use a system resource that is not available at this time. 


[ECONVERT] 


Conversion error. 


One or more characters could not be converted from the source CCSID to the target CCSID. 


[EDAMAGE] 


A damaged object was encountered. 


A referenced object is damaged. The object cannot be used. 


[EFAULT] 


The address used for an argument is not correct. 
In attempting to use an argument in a call, the system detected an address that is not valid. 
While attempting to access a parameter passed to this function, the system detected an address that 


is not valid. 


[EFILECVT] 


File ID conversion of a directory failed. 


Try to run the Reclaim Storage (RCLSTG) command to recover from this error. 


[EINTR] 


Interrupted function call. 
[EINVAL] 
The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on an object and 
the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. 


[EIO] 


Input/output error. 
A physical I/O error occurred. 


A referenced object may be damaged. 


[ELOOP] 
A loop exists in the symbolic links. 
This error is issued if the number of symbolic links encountered is more than POSIX_S YMLOOP 


(defined in the limits.h header file). Symbolic links are encountered during resolution of the 
directory or path name. 


[ENAMETOOLONG] 


A path name is too long. 
A path name is longer than PATH_MAX characters or some component of the name is longer than 
NAME_MAX characters while _POSIX_NO_TRUNC is in effect. For symbolic links, the length 


of the name string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and 
NAME_MAxX values can be determined using the pathconf() function. 


[ENOENT] 
No such path or directory. 


The directory or a component of the path name specified does not exist. 


A named file or directory does not exist or is an empty string. 


[ENOMEM] 


Storage allocation request failed. 
A function needed to allocate storage, but no storage is available. 


There is not enough memory to perform the requested function. 


[ENOSPC] 
No space available. 
The requested operations required additional space on the device and there is no space left. This 
could also be caused by exceeding the user profile storage limit when creating or transferring 
ownership of an object. 


Insufficient space remains to hold the intended file, directory, or link. 


[ENOTAVAIL] 
Independent Auxiliary Storage Pool (ASP) is not available. 


The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage (RCLSTG) 
processing. 


To recover from this error, wait until processing has completed for the independent ASP. 


[ENOTDIR] 


Not a directory. 


A component of the specified path name existed, but it was not a directory when a directory was 
expected. 


Some component of the path name is not a directory, or is an empty string. 


[ENOTSAFE] 


Function is not allowed in a job that is running with multiple threads. 


[ENOTSUP] 


Operation not supported. 


The operation, though supported in general, is not supported for the requested object or the 
requested arguments. 


[EOVERFLOW] 


Object is too large to process. 
The object's data size exceeds the limit allowed by this function. 


The file size in bytes cannot be represented correctly in the structure pointed to by buf (the file is 
larger than 2GB minus 1 byte). 


[EPERM] 
Operation not permitted. 


You must have appropriate privileges or be the owner of the object or other resource to do the 
requested operation. 


[EROOBJ] 
Object is read only. 


You have attempted to update an object that can be read only. 


[ESTALE] 
File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may have been deleted 
at the server. 


[EUNKNOWN] 
Unknown system state. 


The operation failed because of an unknown system state. See any messages in the job log and 
correct any errors that are indicated, then retry the operation. 


If interaction with a file server is required to access the object, errno could indicate one of the following 
errors: 
[EADDRNOTAVAIL] 

Address not available. 
[ECONNABORTED] 

Connection ended abnormally. 
[ECONNREFUSED] 

The destination socket refused an attempted connect operation. 
[ECONNRESET] 

A connection with a remote socket was reset by that socket. 
[EHOSTDOWN] 


A remote host is not available. 
[EHOSTUNREACH] 

A route to the remote host is not available. 
[ENETDOWN] 

The network is not currently available. 
[ENETRESET] 

A socket is connected to a host that is no longer available. 
[ENETUNREACH] 

Cannot reach the destination network. 
[ESTALE] 

File or object handle rejected by server. 

If you are accessing a remote file through the Network File System, the file may have been deleted 

at the server. 
[ETIMEDOUT] 

A remote host did not respond within the timeout period. 
[EUNATCH] 


The protocol required to support the specified address family is not available at this time. 


Error Messages 


The following messages may be sent from this function: 
CPE3418 E 

Possible APAR condition or hardware failure. 
CPFAO0D4 E 

File system error occurred. Error number &1. 
CPF3CF2 E 

Error(s) occurred during running of &1 API. 
CPF9872 E 


Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 


1. This function will fail with error code [ENOTSAFE] when both of the following conditions occur: 


o Where multiple threads exist in the job. 


oO The object this function is operating on resides in a file system that is not threadsafe. Only 
the following file systems are threadsafe for this function: 


m Root 
m QOpenSys 


m User-defined 


wg QNTC 

m QSYS.LIB 

m =Independent ASP QSYS.LIB & 
gw QOPT 


2. QSYS.LIB #and Independent ASP QSYS.LIB “File System Differences 


The stat() function could return zero for the st_atime value (in the stat structure) under some 
conditions. 


3. QDLS File System Differences 


If the date corresponding to the st_atime, st_mtime, or st_ctime value precedes 1970, stat() returns 
zero for that value. Also, if the specified path is /QDLS, stat() returns zero for all three values 
st_atime, st_mtime, and st_ctime. 


4. QOPT File System Differences 


The value for st_atime will always be zero. The value for st_ctime will always be the creation date 
and time of the file or directory. 


The user, group, and other mode bits are always on for an object that exists on a volume not 
formatted in Universal Disk Format (UDF). 


If the object exists on a volume formatted in Universal Disk Format (UDF), the authorization that is 
checked for the object and preceding directories in the path name follows the rules described in 
Figure 1-74, "Authorization Required for stat()." If the object exists on a volume formatted in some 


other media format, no authorization checks are made on the object or on each directory in the path 
name. The volume authorization list is checked for *USE authority regardless of the media format 
of the volume. 


stat on /QOPT will always return 2,147,483,647 for size fields. 
stat on optical volumes will return the volume capacity or 2,147,483,647, whichever is smaller. 


The file access time is not changed. 


5. Network File System Differences 


Local access to remote files through the Network File System may produce unexpected results due 
to conditions at the server. Once a file is open, subsequent requests to perform operations on the 
file can fail because file attributes are checked at the server on each request. If permissions on the 
file are made more restrictive at the server or the file is unlinked or made unavailable by the server 
for another client, your operation on an open file descriptor will fail when the local Network File 
System receives these updates. The local Network File System also impacts operations that retrieve 
file attributes. Recent changes at the server may not be available at your client yet, and old values 
may be returned from operations. (Several options on the Add Mounted File System (ADDMFS) 
command determine the time between refresh operations of local data.) 


6. QNetWare File System Differences 


The QNetWare file system does not fully support mode bits. See Netware on iSeries in the iSeries 
Information Center for more information. 


7. This function will fail with the [EOVERFLOW] error if the file size in bytes cannot be represented 
correctly in the structure pointed to by buf (the file is larger than 2GB minus | byte). 


8. When you develop in C-based languages and this function is compiled with _LARGE_FILES 
defined, it will be mapped to fstat64(). Note that the type of the buf parameter, struct stat *, also 
will be mapped to type struct stat64 *. 


Related Information 


e The <sys/stat.h> file (see Header Files for UNIX-Type Functions) 


e The <sys/types.h> file (see Header Files for UNIX-Type Functions) 


e chmod()--Change File Authorizations 


e chown()--Change Owner and Group of File 


@ creat()--Create or Rewrite File 


e dupQ--Duplicate Open File Descriptor 


e fcntlQ--Perform File Control Command 


e fstatQ--Get File Information by Descriptor 
e linkQ--Create Link to File 


e IstatQ--Get File or Link Information 
e mkdir()--Make Directory 


@ open()--Open File 
e QlgStatQ--Get File Information (using NLS-enabled path name) 


e read()--Read from Descriptor 

e readlink(Q--Read Value of Symbolic Link 

e stat64()--Get File Information (Large File Enabled) 
e@ symlinkQ--Make Symbolic Link 

e unlinkQ--Remove Link to File 


@ utime()--Set File Access and Modification Times 


@ write(--Write to Descriptor 


Example 
The following example gets status information about a file: 


#include <sys/types.h> 
#include <sys/stat.h> 
#include <stdio.h> 


#include <time.h> 


main() { 
struct stat info; 


if (stat("/", &info) != 0) 
perror("stat() error"); 
else { 
puts("stat() returned the following information about root f/s:"); 
printf(" inode: Sda\n", (int) info.st_ino); 
printf (" dev id: Sd\n", (int) info.st_dev); 
printf (" mode: 308x\n", info.st_mode); 
printf(" links: Sda\n", info.st_nlink); 
pLrinte(” uid: Sda\n", (int) info.st_uid); 
printf (" gid: sda\n", (int) info.st_gid); 


} 


Output: note that the following information will vary from system to system. 


stat() returned the following information about root f/s: 
inode: 0 
dev id: 1 
mode: 01000led 
links: 3 
uid: 137 
gid: 500 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


stat64()--Get File Information (Large File 
Enabled) 


Syntax 


#include <sys/stat.h> 


int stat64(const char *path, struct stat64 *buf); 


Threadsafe: Conditional; see Usage Notes. 


The stat64() function gets status information about a specified file and places it in the area of memory 
pointed to by the buf argument. 


If the named file is a symbolic link, stat64(Q) resolves the symbolic link. It also returns information about 
the resulting file. 


stat64() is enabled for large files. It is capable of operating on files larger than 2GB minus | byte and 
returning correct sizes. 


For additional information about authorities required, error conditions, and examples, see stat()--Get File 
Information. 


Parameters 


path 
(Input) A pointer to the null-terminated path name of the file from which information is required. 
This parameter is assumed to be represented in the CCSID (coded character set identifier) currently 


in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented 
in the default CCSID of the job. 


See QlgStat64()--Get File Information (large file enabled and using NLS-enabled path name) for a 
description and an example of supplying the path in any CCSID. 


buf 


(Output) A pointer to the area to which the information should be written. 


The information is returned in the following stat64 structure, as defined in the <sys/stat.h> header file: 


mode_t st_mode A bit string indicating the permissions and privileges of the 
file. Symbols are defined in the <sys/stat.h> header file to refer 
to bits in a mode_t value; these symbols are listed in 


chmod()--Change File Authorizations. 


ino_t 


uid_t 
gid_t 


off64_t 


time_t 
time_t 
time_t 


dev_t 


size_t 


nlink_t 


unsigned short 


unsigned long long 


unsigned int 


st_ino 


st_uid 
st_gid 


st_size 


st_atime 
st_mtime 
st_ctime 


st_dev 


st_blksize 


st_nlink 


st_codepage 


st_allocsize 


st_ino_gen_id 


The file ID for the object. This number uniquely identifies the 
object within a file system. When st_ino and st_dev are used 
together, they uniquely identify the object on the system. 


The numeric user ID (uid) of the owner of the file. 
The numeric group ID (gid) for the file. 


Defined as follows for each file type: 
Regular File 
The number of data bytes in the file. 
Directory 
The number of bytes allocated to the directory. 
Symbolic Link 


The number of bytes in the path name stored in the 
symbolic link. 


Local Socket 
Always zero. 
OS/400 Native Object 


This value is dependent on the object type. 
The most recent time the file was accessed. 


The most recent time the contents of the file were changed. 
The most recent time the status of the file was changed. 


The file system ID to which the object belongs. This number 
uniquely identifies the file system to which the object belongs. 
When st_ino and st_dev are used together, they uniquely 
identify the object on the system. #This field will be 
4,294,967,295 if the value could not fit in the specified dev_t 
field. The complete value will be in the st_dev64 field.“ 


The block size of the file in bytes. 
The number of links to the file. #*This field will be 65,535 if 
the value could not fit in the specified nlink_t field. The 


complete value will be in the st_nlink32 field.“ 


The code page derived from the CCSID used for the data in the 
file or the extended attributes of the directory. If the returned 
value of this field is 0, a code page could not be derived. 


The number of bytes allocated to the file. 


The generation ID associated with the file ID. 


qpO0l_objtype_t 


st_objtype 


The iSeriesO object type; for example, *STMF or *DIR. Refer 


to CL thse Petes a list of the iSeries object types. 


= char st_reserved2[5] Reserved.*& 

2 dev-t st_rdev The device ID of the object if the object is a character special 
file or block special file. This number uniquely identifies the 
file device. This field will be 4,294,967,295 if the value could 
not fit in the specified dev_t field. The complete value will be 
in the st_rdev64 field. *& 

2 dev64_t st_rdev64 The device ID of the object in 64 bit format. See st_rdev for 
more information.*& 

= dev64_t st_dev64 The file system ID to which the object belongs in 64 bit 
format. See st_dev for more information.*& 

= nlink32_t st_nlink32 The number of links to the file.“ 

= char st_reserved1[26] Reserved.*& 


The CCSID used for the data in the file or the extended 
attributes of the directory. 


unsigned short st_ccsid 


Values of time_t are given in terms of seconds since a fixed point in time called the Epoch. 
You can examine properties of a mode_t value from the st_mode field using a collection of macros defined 
in the <sys/stat.h> header file. If mode is a mode_t value, then: 
S_ISBLK(mode) 
Is nonzero for block special files 
S_ISCHR(mode) 
Is nonzero for character special files 
S_ISDIR(mode) 
Is nonzero for directories 
S_ISFIFO(mode) 
Is nonzero for pipes and FIFO special files 
S_ISREG(mode) 
Is nonzero for regular files 
S_ISLNK(mode) 
Is nonzero for symbolic links 
S_ISSOCK(mode) 
Is nonzero for local sockets 
S_ISNATIVE(mode) 


Is nonzero for OS/400 native objects 


Usage Notes 


1. When you develop in C-based languages, the prototypes for the 64-bit APIs are normally hidden. 
To use either the stat64Q) API or the QlgStat64() API and the struct stat64 data type, you must 
compile the source with LLARGE_FILE_API defined. 


2. All of the usage notes for stat() also apply to stat64() and to QlgStat64(). See Usage Notes in the 
stat() API. 


Top | UNIX-Type APIs | APIs by category 


statvis()--Get File System Information 


Syntax 


#include <sys/statvfs.h> 


int statvfs(const char *path, struct statvfs *buf); 


Threadsafe: Conditional; see Usage Notes. 


The statvfs() function gets status information about the file system that contains the file named by the path 
argument. The information will be placed in the area of memory pointed to by the buf argument. 


If the named file is a symbolic link, statvfs() resolves the symbolic link. 


Parameters 


path 


(Input) A pointer to the null-terminated path name of the file from which file system information is 
required. 


This parameter is assumed to be represented in the CCSID (coded character set identifier) currently 
in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented 
in the default CCSID of the job. 


See QlgStatvfsQ--Get File System Information (using NLS-enabled path name) for a description 
and an example of supplying the path in any CCSID. 


buf 


(Output) A pointer to the area to which the information should be written. 


The information is returned in the following statvfs structure, as defined in the <sys/statvfs.h> header file. 
Signed fields of the statvfs structure that are not supported by the mounted file system will be set to -1. 


unsigned long f_bsize The file system block size in bytes. Some file systems may 
return zero in this field. If this field is zero, then the contents of 
the f_blocks, f_bfree, and f_bavail fields are undefined. 


unsigned long f_frsize The fundamental file system block size in bytes. Some file 
systems may return zero in this field. If this field is zero, then 
the contents of the f_blocks, f_bfree, and f_bavail fields are 
undefined. 


_Bin8 f_blocks The total number of blocks in the file system in terms of 
f_frsize. 


_Bin8 f_bfree The total number of free blocks in the file system. 


_ Bing 


unsigned long 
unsigned long 


unsigned long 


unsigned long 


unsigned long 


unsigned long 


unsigned long 


long 


long 


= char 


2 unsigned long 


long 
char 


f_bavail 


f_files 
f_ffree 


f_favail 


f_fsid 


f_flag 


f_namemax 


f_pathmax 


f_objlinkmax 


f_dirlinkmax 
f_reserved1[4] 
f_fsid64 


f_basetype[80] 


The total number of free blocks available to a non-privileged 
process. 


The total number of file serial numbers. 
The total number of free file serial numbers. 


The number of free file serial numbers available to a 
non-privileged process. 


The file system ID. This field will be 4,294,967,295 if the 
value could not fit in the specified unsigned long field.*& 


File system flags. Symbols are defined in the <sys/statvfs.h> 
header file to refer to bits in this field (see The f_flags field). 


The maximum file name length in the file system. Some file 
systems may return the maximum value that can be stored in 
an unsigned long to indicate the file system has no maximum 
file name length. The maximum value that can be stored in an 
unsigned long is defined in <limits.h> as ULONG_MAX. 


This value is the number of bytes allowed in the file name if it 
were encoded in the CCSID of the job. If the CCSID is mixed, 
this number is an estimate and may be larger than the actual 
allowable maximum. 


The maximum path length in the file system. Some file 
systems may return the maximum value that can be stored in 
an unsigned long to indicate the file system has no maximum 
path length. The maximum value that can be stored in an 
unsigned long is defined in <limits.h> as ULONG_MAX. 


This value is the number of bytes allowed in the file name if it 
were encoded in the CCSID of the job. If the CCSID is mixed, 
this number is an estimate and may be larger than the actual 
allowable maximum. 


The maximum number of hard links for objects other than 
directories. 


The maximum number of hard links for a directory. 
Reserved.*& 

The file system ID in 64 bit format.%& 

The NULL-terminated file system type name. The text in this 
field will be returned in the CCSID (coded character set 
identifier) currently in effect for the job. If the CCSID of the 


job is 65535, this is assumed to be represented in the default 
CCSID of the job. 


The f_flags field 


The following symbols are defined in the <sys/statvfs.h> header file to refer to bits that may be returned in 
the f_flags field: 


ST_RDONLY 

The file system is mounted for read-only access. 
ST_NOSUID 

The file system does not support setuid/setgid semantics. 
ST_CASE_SENSITIVE 

The file system is case sensitive. 
ST_CHOWN_RESTRICTED 


The file system restricts the changing of the owner or primary group to a process that has the 
appropriate privileges. 
ST_THREAD_SAFE 


The file system is thread-safe. Thread-safe APIs may operate on objects in this file system in a 
thread-safe manner. 


ST_DYNAMIC_MOUNT 

The file system allows itself to be dynamically mounted and unmounted. 
ST_NO_MOUNT_OVER 

The file system does not allow any part of it to be mounted over. 
ST_NO_EXPORTS 


The file system does not allow any of its objects to be exported to the Network File System (NFS) 
Server. 


ST_SYNCHRONOUS 
The file system supports the "synchronous write" semantic of NFS Version 2. 


Authorities 


Note: Adopted authority is not used. 


Figure 1-75. Authorization Required for statvfs() 


Authority 
Object Referred to Required |errno 
[Each directory in the path name that precedes the object [*x [EACCES 
[Object [None [None 


Return Value 


0 
statvfs() was successful. The information is returned in buf. 
-l 


statvfs() was not successful. The errno global variable is set to indicate the error. 


Error Conditions 


If statvfs() is not successful, errno usually indicates one of the following errors. Under some conditions, 


errno could indicate an error other than those listed here. 
[EACCES] 


Permission denied. 
An attempt was made to access an object in a way forbidden by its object access permissions. 
The thread does not have access to the specified file, directory, component, or path. 


If you are accessing a remote file through the Network File System, update operations to file 
permissions at the server are not reflected at the client until updates to data that is stored locally by 
the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) 
command determine the time between refresh operations of local data.) Access to a remote file may 
also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote 


systems. 


[EAGAIN] 


Operation would have caused the process to be suspended. 
[EBADFID] 

A file ID could not be assigned when linking an object to a directory. 

The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as possible. 


[EBADNAME] 


The object name specified is not correct. 
[EBUSY] 
Resource busy. 


An attempt was made to use a system resource that is not available at this time. 


[ECONVERT] 


Conversion error. 


One or more characters could not be converted from the source CCSID to the target CCSID. 


[EDAMAGE] 


A damaged object was encountered. 


A referenced object is damaged. The object cannot be used. 


[EFAULT] 


The address used for an argument is not correct. 
In attempting to use an argument in a call, the system detected an address that is not valid. 
While attempting to access a parameter passed to this function, the system detected an address that 


is not valid. 


[EFILECVT] 


File ID conversion of a directory failed. 


Try to run the Reclaim Storage (RCLSTG) command to recover from this error. 


[EINTR] 


Interrupted function call. 
[EINVAL] 
The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on an object and 
the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. 


[EIO] 


Input/output error. 
A physical I/O error occurred. 


A referenced object may be damaged. 


[ELOOP] 
A loop exists in the symbolic links. 
This error is issued if the number of symbolic links encountered is more than POSIX_SYMLOOP 


(defined in the limits.h header file). Symbolic links are encountered during resolution of the 
directory or path name. 


[ENAMETOOLONG] 
A path name is too long. 
A path name is longer than PATH_MAX characters or some component of the name is longer than 
NAME_MAX characters while POSIX_NO_TRUNC is in effect. For symbolic links, the length 


of the name string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and 
NAME_MAxX values can be determined using the pathconf() function. 


[ENOENT] 


No such path or directory. 
The directory or a component of the path name specified does not exist. 


A named file or directory does not exist or is an empty string. 


[ENOMEM] 


Storage allocation request failed. 
A function needed to allocate storage, but no storage is available. 


There is not enough memory to perform the requested function. 


[ENOSPC] 
No space available. 
The requested operations required additional space on the device and there is no space left. This 
could also be caused by exceeding the user profile storage limit when creating or transferring 
ownership of an object. 


Insufficient space remains to hold the intended file, directory, or link. 


[ENOTAVAIL] 
Independent Auxiliary Storage Pool (ASP) is not available. 


The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage (RCLSTG) 
processing. 


To recover from this error, wait until processing has completed for the independent ASP. 


[ENOTDIR] 


Not a directory. 


A component of the specified path name existed, but it was not a directory when a directory was 
expected. 


Some component of the path name is not a directory, or is an empty string. 


[ENOTSAFE] 


Function is not allowed in a job that is running with multiple threads. 
[EPERM] 
Operation not permitted. 
You must have appropriate privileges or be the owner of the object or other resource to do the 


requested operation. 


[ESTALE] 


File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may have been deleted 
at the server. 


[EUNKNOWN] 
Unknown system state. 


The operation failed because of an unknown system state. See any messages in the job log and 
correct any errors that are indicated, then retry the operation. 


If interaction with a file server is required to access the object, errno could indicate one of the following 
errors: 
[EADDRNOTAVAIL] 
Address not available. 
[ECONNABORTED] 
Connection ended abnormally. 
[ECONNREFUSED] 
The destination socket refused an attempted connect operation. 
[ECONNRESET] 
A connection with a remote socket was reset by that socket. 
[EHOSTDOWN] 
A remote host is not available. 
[EHOSTUNREACH] 
A route to the remote host is not available. 
[ENETDOWN] 
The network is not currently available. 
[ENETRESET] 
A socket is connected to a host that is no longer available. 
[ENETUNREACH] 
Cannot reach the destination network. 
[ESTALE] 
File or object handle rejected by server. 
If you are accessing a remote file through the Network File System, the file may have been deleted 
at the server. 
[ETIMEDOUT] 
A remote host did not respond within the timeout period. 
[EUNATCH] 


The protocol required to support the specified address family is not available at this time. 


Error Messages 


The following messages may be sent from this function: 
CPE3418 E 

Possible APAR condition or hardware failure. 
CPFA0D4 E 

File system error occurred. Error number &1. 
CPF3CF2 E 

Error(s) occurred during running of &1 API. 
CPF9872 E 


Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 


1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 
oO Where multiple threads exist in the job. 


oO The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


m Root 

m QOpenSys 

m User-defined 

gw QNTC 

mw QSYS.LIB 

m {Independent ASP QSYS.LIB & 
gw QOPT 


2. Root ("/") and QOpenSys File System Differences 


These file systems return the f_flag field with the ST_NOSUID flag bit turned off. However, 
support for the setuid/setgid semantics is limited to the ability to store and retrieve the S_ISUID 
and S_ISGID flags when these file systems are accessed from the Network File System server. 


3. Network File System Differences 


Local access to remote files through the Network File System may produce unexpected results due 
to conditions at the server. The local Network File System also impacts operations that retrieve file 
attributes. Recent changes at the server may not be available at your client yet, and old values may 
be returned from operations. (Several options on the Add Mounted File System (ADDMEFS) 
command determine the time between refresh operations of local data.) 


4. When you develop in C-based languages and this function is compiled with [LARGE_FILES 
defined, it will be mapped to statvfs64(). Additionally, the struct statvfs data type will be mapped 
to a struct statvfs64. 


Related Information 


e The <sys/statvfs.h> file (see Header Files for UNIX-Type Functions) 


e The <sys/types.h> file (see Header Files for UNIX-Type Functions) 


e chmod(Q)--Change File Authorizations 


e chown()--Change Owner and Group of File 


@ creat()--Create or Rewrite File 


e dupQ--Duplicate Open File Descriptor 


e fentlO--Perform File Control Command 


e fstatvfsQ--Get File System Information by Descriptor 
e linkQ--Create Link to File 


@ open()--Open File 
e QlegStatvfsQ--Get File System Information (using NLS-enabled path name) 


e read()--Read from Descriptor 


e statvfs64(--Get File System Information (64-Bit Enabled) 


e unlink()--Remove Link to File 


@ utime()--Set File Access and Modification Times 


@ write()--Write to Descriptor 


Example 


The following example gets status information about a file system: 


#include <sys/statvfs.h> 
#include <stdio.h> 


main() { 
struct statvfs info; 


if (-1 == statvfs("/", &info)) 
perror ("statvfs() error"); 
else { 


puts ("statvfs() returned the following information"); 
puts("about the Root ('/') file system:"); 


printf(" f_bsize : Su\n", info.f_bsize); 
printf(" f£_blocks : S08X%08X\n", 


*( (int *)é&info.f_blocks[0]), 

*( (int *)é&info.f_blocks[4])); 
printf(" f_bfree : S08X%08X\n", 

*( (int *)&info.f_bfree[0]), 

*((int *)éinfo.f_bfree[4])); 
printf(" f_files : Su\n", info.f_files); 
printf(" f_ffree : Su\n", info.f_ffree); 


prince (" 
pLrinte (" 
printe’(" 
printf (" 
printt (" 


} 


f_fsid : Su\n", info.f_fsid); 


f_flag : 6X\n", info.f_flag); 
f_namemax : Su\n", info.f_namemax) ; 
f_pathmax : %u\n", info.f_pathmax); 
f_basetype : s\n", info.f_basetype) ; 


Output: The following information will vary from file system to file system. 


statvfs() returned the following information 
about the Root ('/') file system: 
f_bsize 4096 
f_blocks O0000000002BF800 
f_bfree 0000000000091703 
f_files 4294967295 
f_ffree 4294967295 
f_fsid 0 
f_flag 1A 
f_namemax 255 
f_pathmax 4294967295 
f_basetype "root" (/) 


API introduced: V4R2 
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statvis64()--Get File System Information (64-Bit 
Enabled) 


Syntax 


#include <sys/statvfs.h> 


int statvfs64(const char *path, struct statvfs64 *buf) 


Threadsafe: Conditional; see Usage Notes. 


The statvfs64() function gets status information about the file system that contains the file named by the 
path argument. The information is placed in the area of memory pointed to by the buf argument. 


If the named file is a symbolic link, statvfs64() resolves the symbolic link. 


For details about authorities required, error conditions, and examples, see statvfs()--Get File System 
Information. 


Parameters 


path 


(Input) A pointer to the null-terminated path name of the file from which file system information is 
required. 


This parameter is assumed to be represented in the coded character set identifier (CCSID) currently 
in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented 
in the default CCSID of the job. 


See QlgStatvfs64(0--Get File System Information (64-Bit enabled and using NLS-enabled path 
name) for a description and an example of supplying the path in any CCSID. 


buf 


(Output) A pointer to the area to which the information should be written. 


The information is returned in the following statvfs64 structure, as defined in the <sys/statvfs.h> header 
file. Signed fields of the statvfs64 structure that are not supported by the mounted file system will be set to 
-1. 


unsigned long f_bsize The file system block size in bytes. Some file systems may 
return zero in this field. If this field is zero, then the contents of 
the f_blocks, f_bfree, and f_bavail fields are undefined. 


unsigned long f_frsize The fundamental file system block size in bytes. Some file 
systems may return zero in this field. If this field is zero, then 
the contents of the f_blocks, f_bfree, and f_bavail fields are 
undefined. 


unsigned long long 


unsigned long long 


unsigned long long 


unsigned long 
unsigned long 


unsigned long 


unsigned long 


unsigned long 


unsigned long 


unsigned long 


long 


long 


= char 


#* unsigned long 


long 


f_blocks 


f_bfree 


f_bavail 


f_files 
f_ffree 


f_favail 


f_fsid 


f_flag 


f_namemax 


f_pathmax 


f_objlinkmax 


f_dirlinkmax 
f_reserved1[4] 


f_fsid64 


The total number of blocks in the file system in terms of 
f_frsize. 


The total number of free blocks in the file system. 


The total number of free blocks available to a non-privileged 
process. 


The total number of file serial numbers. 
The total number of free file serial numbers. 


The number of free file serial numbers available to a 
non-privileged process. 


The file system ID. 2 This field will be 4,294,967,295 if the 
value could not fit in the specified unsigned long field. 


File system flags. Symbols are defined in the <sys/statvfs.h> 
header file to refer to bits in this field (see The f_flags field). 


The maximum file name length in the file system. Some file 
systems may return the maximum value that can be stored in 
an unsigned long to indicate the file system has no maximum 
file name length. The maximum value that can be stored in an 
unsigned long is defined in <limits.h> as ULONG_MAX. 


This value is the number of bytes allowed in the file name if it 
were encoded in the CCSID of the job. If the CCSID is mixed, 
this number is an estimate and may be larger than the actual 
allowable maximum. 


The maximum path length in the file system. Some file 
systems may return the maximum value that can be stored in 
an unsigned long to indicate the file system has no maximum 
path length. The maximum value that can be stored in an 
unsigned long is defined in <limits.h> as ULONG_MAX. 


This value is the number of bytes allowed in the file name if it 
were encoded in the CCSID of the job. If the CCSID is mixed, 
this number is an estimate and may be larger than the actual 
allowable maximum. 


The maximum number of hard links for objects other than 
directories. 


The maximum number of hard links for a directory. 
Reserved. #* 


The file system ID in 64 bit format. 


char f_basetype[80] The NULL-terminated file system type name. The text in this 
field will be returned in the CCSID (coded character set 
identifier) currently in effect for the job. If the CCSID of the 
job is 65535, this is assumed to be represented in the default 
CCSID of the job. 


For further details about the f_flags field, see statvfs()--Get File System Information. 


Usage Notes 


1. When you develop in C-based languages, the prototypes for the 64-bit APIs are normally hidden. 
To use the statvfs64() API or the QlgStatvfs64() API and the struct statvfs64 data type, you must 
compile the source with the LLARGE_FILE_API macro defined. 


2. All of the usage notes for statvfs() apply to statvfs64( and QlgStatvfs64(). See Usage Notes in the 
statvfs() API. 
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symlink()--Make Symbolic Link 


Syntax 


#include <unistd.h> 


int symlink(const char *pname, const char *slink); 


Threadsafe: Conditional; see Usage Notes. 


The symlink() function creates the symbolic link named by slink with the value specified by pname. File 
access checking is not performed on the file pname, and the file need not exist. In addition, a symbolic link 
can cross file system boundaries. 


If slink names a symbolic link, symlink() fails with the [EEXIST] error. 


A symbolic link path name is resolved in the following manner: 


e@ When acomponent of a path name refers to a symbolic link rather than to a directory, the path 
name contained in the symbolic link is resolved. 


e If the path name in the symbolic link begins with / (slash), the symbolic link path name is resolved 
relative to the root directory for the job. 


If the path name in the symbolic link does not start with / (slash), the symbolic link path name is 
resolved relative to the directory that contains the symbolic link. 


e If the symbolic link is the last component of a path name, it may or may not be resolved. 
Resolution depends on the function using the path name. For example, rename() does not resolve a 
symbolic link when the symbolic link is the final component of either the new or old path name. 
However, open() does resolve a symbolic link when the link is the last component. 


e If the symbolic link is not the last component of the original path name, remaining components of 
the original path name are resolved relative to the symbolic link. 


e@ When a/ (slash) is the last component of a path name and it is preceded by a symbolic link, the 
symbolic link is always resolved. 


Any files and directories to which a symbolic link refers are checked for access permission. 


symlink() sets the access, change, modification, and creation times for the new symbolic link. It also sets 
the change and modification times for the directory that contains the new symbolic link. 


Parameters 


pname 
(Input) A pointer to the null-terminated value of the symbolic link. 
The value of the symbolic link is assumed to be represented in the CCSID (coded character set 


identifier) currently in effect for the job. If the CCSID of the job is 65535, this parameter is 
assumed to be represented in the default CCSID of the job. 


See QlgSymlink--Make Symbolic Link (using NLS-enabled path name) for a description and an 
example of supplying the pname in any CCSID. 


slink 
(Input) A pointer to the null-terminated name of the symbolic link to be created. 
This parameter is assumed to be represented in the CCSID, language, and country or region 


currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be 
represented in the default CCSID of the job. 


See QlgSymlink--Make Symbolic Link (using NLS-enabled path name) for a description and an 
example of supplying the slink in any CCSID. 


Authorities 


Note: Adopted authority is not used. 


Figure 1-76. Authorization Required for symlink() 


Authority 
Object Referred to Required |errno 
[Each directory in the path name preceding the object to be created *x [EACCES 
[Parent directory of object to be created [*WX [EACCES 


Return Value 


0 
symlink() was successful. 
-l 


symlink() was not successful. The errno global variable is set to indicate the error. 


Error Conditions 


If symlink() is not successful, errno usually indicates one of the following errors. Under some conditions, 
errno could indicate an error other than those listed here. 


[EACCES] 


Permission denied. 
An attempt was made to access an object in a way forbidden by its object access permissions. 
The thread does not have access to the specified file, directory, component, or path. 


If you are accessing a remote file through the Network File System, update operations to file 
permissions at the server are not reflected at the client until updates to data that is stored locally by 
the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) 
command determine the time between refresh operations of local data.) Access to a remote file may 


also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote 
systems. 


[EAGAIN] 


Operation would have caused the process to be suspended. 
[EBADFID] 

A file ID could not be assigned when linking an object to a directory. 

The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as possible. 


[EBADNAME] 


The object name specified is not correct. 
[EBUSY] 
Resource busy. 


An attempt was made to use a system resource that is not available at this time. 


[ECONVERT] 


Conversion error. 


One or more characters could not be converted from the source CCSID to the target CCSID. 


[EDAMAGE] 


A damaged object was encountered. 


A referenced object is damaged. The object cannot be used. 


[EEXIST] 


File exists. 
The file specified already exists and the specified operation requires that it not exist. 


The named file, directory, or path already exists. 


[EFAULT] 


The address used for an argument is not correct. 
In attempting to use an argument in a call, the system detected an address that is not valid. 
While attempting to access a parameter passed to this function, the system detected an address that 


is not valid. 


[EFILECVT] 


File ID conversion of a directory failed. 


Try to run the Reclaim Storage (RCLSTG) command to recover from this error. 


[EINTR] 


Interrupted function call. 
[EINVAL] 
The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on an object and 
the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. 


[EIO] 


Input/output error. 
A physical I/O error occurred. 


A referenced object may be damaged. 


[EISDIR] 


Specified target is a directory. 
The path specified named a directory where a file or object name was expected. 


The path name given is a directory. 


[ELOOP] 


A loop exists in the symbolic links. 


This error is issued if the number of symbolic links encountered is more than POSIX_SYMLOOP 
(defined in the limits.h header file). Symbolic links are encountered during resolution of the 
directory or path name. 


[ENAMETOOLONG] 


A path name is too long. 


A path name is longer than PATH_MAX characters or some component of the name is longer than 
NAME_MAX characters while _POSIX_NO_TRUNC is in effect. For symbolic links, the length 
of the name string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and 
NAME_MAX values can be determined using the pathconf() function. 


[ENOENT] 
No such path or directory. 


The directory or a component of the path name specified does not exist. 


A named file or directory does not exist or is an empty string. 


[ENOMEM] 


Storage allocation request failed. 
A function needed to allocate storage, but no storage is available. 


There is not enough memory to perform the requested function. 


[ENOSPC] 
No space available. 
The requested operations required additional space on the device and there is no space left. This 
could also be caused by exceeding the user profile storage limit when creating or transferring 
ownership of an object. 


Insufficient space remains to hold the intended file, directory, or link. 


[ENOSYS] 


Function not implemented. 


An attempt was made to use a function that is not available in this implementation for any object or 
any arguments. 


The path name given refers to an object that does not support this function. 


[ENOTAVAIL] 
Independent Auxiliary Storage Pool (ASP) is not available. 


The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage (RCLSTG) 
processing. 


To recover from this error, wait until processing has completed for the independent ASP. 


[ENOTDIR] 


Not a directory. 


A component of the specified path name existed, but it was not a directory when a directory was 
expected. 


Some component of the path name is not a directory, or is an empty string. 


[ENOTSAFE] 


Function is not allowed in a job that is running with multiple threads. 


[ENOTSUP] 


Operation not supported. 


The operation, though supported in general, is not supported for the requested object or the 


requested arguments. 


[EPERM] 


Operation not permitted. 


You must have appropriate privileges or be the owner of the object or other resource to do the 
requested operation. 


[EROOBJ] 
Object is read only. 


You have attempted to update an object that can be read only. 


[ESTALE] 
File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may have been deleted 
at the server. 


[EUNKNOWN] 
Unknown system state. 


The operation failed because of an unknown system state. See any messages in the job log and 
correct any errors that are indicated, then retry the operation. 


Error Messages 


The following messages may be sent from this function: 
CPE3418 E 

Possible APAR condition or hardware failure. 
CPFA0D4 E 

File system error occurred. Error number &1. 
CPF3CF2 E 

Error(s) occurred during running of &1 API. 
CPF9872 E 


Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 


1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 
oO Where multiple threads exist in the job. 


oO. The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


= Root 

m QOpenSys 

m User-defined 

wg QNTC 

mw QSYS.LIB 

m Independent ASP QSYS.LIB & 
gw QOPT 


2. File System Differences 


The following file systems do not support symlink(Q: 
o QSYS.LIB 
o Independent ASP QSYS.LIB 
o QDLS 
Oo QOPT 
oO QFileSvr.400 
Oo QNetWare 
Oo QNTC 


Related Information 


e The <unistd.h> file (see Header Files for UNIX-Type Functions) 
e@ link()--Create Link to File 


e QlgSymlink--Make Symbolic Link (using NLS-enabled path name) 
e readlink(Q)--Read Value of Symbolic Link 


e unlinkQ--Remove Link to File 


Example 
The following example uses symlink(): 


#include <stdio.h> 
#include <unistd.h> 
#include <sys/types.h> 
#include <sys/stat.h> 
#include <fcntl.h> 
#include <stdlib.h> 


main() { 
char fn[]="readlink.file"; 
char sl[]="readlink.symlink"; 


char buf[30]; 
int file_descriptor; 


if ((file_descriptor = creat(fn, S_IWUSR)) < 0) 
perror("creat() error"); 


else { 
close(file_descriptor) ; 
if (symlink(fn, sl) != 0) 
perror ("symlink() error"); 


else { 
if (readlink(sl, buf, sizeof(buf)) < 0) 


perror ("readlink() error"); 
else printf ("readlink() returned '%s' 
for 'Ss'\n", buf, sl); 


unlink(sl); 


} 


unlink (fn); 
} 
} 


Output: 


readlink() returned 'readlink.file' for 'readlink.symlink' 


API introduced: V3R1 
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sysconf()--Get System Configuration Variables 


Syntax 


#include <unistd.h> 


long sysconf (int name); 


Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Yes 


The sysconf() function returns the value of a system configuration option. The configuration option to be 
obtained is specified by name. 


Parameters 


name 


(Input) The named variable whose value is to be returned. 


The value of name can be any one of the following symbols defined in the <unistd.h> header file, each 
corresponding to a system configuration option: 


_SC_ARG_MAX 


_SC_CHILD_MAX 


_SC_CLK_TCK 


_SC_JOB_CONTROL 


_SC_NGROUPS_MAX 


(Not supported by the iSeries server). Represents ARG_MAX, which indicates 
the maximum number of bytes of arguments and environment data that can be 
passed in an exec function. 


(Not supported by the iSeries server). Represents CHILD_MAX, which 
indicates the maximum number of jobs that a real user ID (uid) can have 
running simultaneously. 


Represents the CLK_TCK macro, which indicates the number of clock ticks in 
a second. CLK_TCK is defined in the <time.h> header file. 


(Not supported by the iSeries server). Represents the 
_POSIX_JOB_CONTROL macro, which indicates that certain job control 
operations are implemented by this version of the operating system. If 
_POSIX_JOB_CONTROL is defined (in the <unistd.h> header file), various 
APIs, such as setpgid(), provide more function than when the macro is not 
defined. 


Represents NGROUPS_MAX, which indicates the maximum number of 
supplementary group IDs (gid) that can be associated with a job. 


_SC_OPEN_MAX Represents OPEN_MAX, which indicates the maximum number of files that a 
single job can have open at one time. 


_SC_PAGESIZE Represents the system hardware page size. The symbol _SC_PAGESIZE is 
defined as the decimal value 11. 


_SC_PAGE_SIZE Represents the system hardware page size. The symbol _SC_PAGE_SIZE is 
defined as the decimal value 12. 


_SC_SAVED_IDS (Not supported by the iSeries server). Represents the _POSIX_SAVED_IDS 
macro, which indicates that this POSIX implementation has a saved set uid and 
a saved set gid. If the macro exists, it is defined in the <unistd.h> header file. 
This symbol affects the behavior of such functions as setuid() and setgid(). 


_SC_STREAM_MAX Represents the STREAM_MAX macro, which indicates the maximum number 
of streams that a job can have open at one time. The macro is defined in the 
<limits.h> header file. 


_SC_TZNAME_MAX (Not supported by the iSeries server). Represents the TZNAME_ MAX macro, 
which indicates the maximum length of the name of a time zone. If the macro 
exists, it is defined in the <limits.h> header file. 


_SC_VERSION (Not supported by the iSeries server). Represents the _POSIX_VERSION 
macro, which indicates the version of the POSIX.1 standard that the system 
conforms to. If the macro exists, it is defined in the <unistd.h> header file. 


_SC_CCSID Represents the default coded character set identifier (CCSID) used internally 
for integrated file system path names. A CCSID uniquely identifies the coded 
graphic character representation of a path name and includes such information 
as the character set and code page identifier. The symbol _SC_CCSID is 
defined as the decimal value 10. 


Authorities 


No authorization is required. 


Return Value 


value _ sysconf() was successful. The value associated with the specified option is returned. 


-1 One of the following has occurred: 


e The variable corresponding to name is valid but is not supported by the system. The 
errno global variable is not changed. 


e sysconf() failed in some other way. The errno is set to indicate the error. 


Error Conditions 


If sysconf() is not successful, errno usually indicates one of the following errors. Under some conditions, 
errno could indicate an error other than those listed here. 


[EBADFID]_ A file ID could not be assigned when linking an object to a directory. 
The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as 
possible. 


[EINVAL] The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on an 
object and the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. 


The value for name is not valid. 


Error Messages 


The following messages may be sent from this function: 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF3CF2 E Error(s) occurred during running of &1 API. 


Related Information 


e The <unistd.h> file (see Header Files for UNIX-Type Functions) 


Example 
See Code disclaimer information for information pertaining to code examples. 


The following example determines the value of OPEN_MAX: 


#include <stdio.h> 
#include <unistd.h> 
#include <errno.h> 


main() { 
long result; 


errno = 0; 
puts ("examining OPEN_MAX limit"); 
if ((result = sysconf (_SC_OPEN_MAX)) == -1) 


if (errno == 0) 
puts ("OPEN_MAX is not supported."); 
else perror("sysconf() error"); 
else 
printf ("OPEN_MAX is %ld\n", result); 


Output: 


examining OPEN_MAX limit 
OPEN_MAX is 200 
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umask()--Set Authorization Mask for Job 


Syntax 


#include <sys/stat.h> 


mode_t umask (mode_t cmask) ; 
Threadsafe: Yes 


Every job has a file creation mask. When a job starts, the value of the file creation mask is zero. The value 
of zero means that no permissions are masked when a file or directory is created in the job. The umask() 
function changes the value of the file creation mask for the current job to the value specified in cmask. 


The cmask argument controls file permission bits that should be set whenever the job creates a file. File 
permission bits set to 1 in the file creation mask are set to 0 in the file permission bits of files that are 
created by the job. 

For example, if a call to open() specifies a mode argument with file permission bits, the file creation mask 
of the job affects the mode argument; bits that are 1 in the mask are set to 0 in the mode argument and, 
therefore, in the mode of the created file. 


Only the file permission bits of cmask are used. The other bits in cmask must be cleared (not set), or the 
CPFAOD3 message is issued. 


Parameters 


cmask 


(Input) The new value of the file creation mask. For a description of the permission bits, see 


chmod()--Change File Authorizations. 


Authorities 


No authorization is required. 


Return Value 


umask() returns the previous value of the file creation mask. It does not return -1 or set the errno global 
variable. 


Error Conditions 


None. 


Error Messages 


The following messages may be sent from this function: 
CPE3418 E 

Possible APAR condition or hardware failure. 
CPFAO0D3 E 

cmask parameter is not valid. 
CPFA0D4 E 

File system error occurred. Error number &1. 
CPF3CF2 E 

Error(s) occurred during running of &1 API. 
CPF9872 E 


Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 


1. QNTC File System Differences 


umask() does not update the file creation mask for QNTC. The settings specified in cmask are 
ignored. 


Related Information 


e The <sys/stat.h> file (see Header Files for UNIX-Type Functions) 


e chmod(Q--Change File Authorizations 


@ creat()--Create or Rewrite File 
e mkdir()--Make Directory 


open()--Open File 


Example 
The following example uses umask(): 


#include <stdio.h> 
#include <fcntl.h> 
#include <sys/stat.h> 


int file_descriptor; 
struct stat info; 


umask (S_IRWXG) ; 


if ((file_descriptor = 
creat ("umask.file", S_IRWXU|S_IRWXG)) < 0) 
perror("creat() error"); 
else { 


fstat (file_descriptor, &info); 
printf ("permissions are: %08x\n", info.st_mode); 
close(file_descriptor) ; 
unlink ("umask.file"); 
} 
Output: 


permissions are: 000081c0 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


unlink()--Remove Link to File 


Syntax 


#include <unistd.h> 


int unlink(const char *path); 


Threadsafe: Conditional; see Usage Notes. 


The unlink() function removes a directory entry that refers to a file. This unlink() deletes the link named 
by path and decrements the link count for the file itself. 


If the link count becomes zero and no job currently has the file open, the file itself is deleted. The space 
occupied by the file is freed for new use, and the current contents of the file are lost. If one or more jobs 
have the file open when the last link is removed, unlink() removes the link, but the file itself is not 
removed until the last job closes the file. 


unlink() cannot be used to remove a directory; use rmdir() instead. 


If path refers to a symbolic link, unlink() removes the symbolic link but not a file or directory named by 
the contents of the symbolic link. 


If unlinkQ succeeds, the change and modification times for the parent directory are updated. If the link 
count of the file is not zero, the change time for the file is also updated. If unlink() fails, the link is not 
removed. 


If the file is checked out, unlink() fails with the [EBUSY] error. If the file is marked "read-only", unlink() 
fails with the [EROOBJ] error. 


Parameters 


path 
(Input) A pointer to the null-terminated path name of the file to be unlinked. 
This parameter is assumed to be represented in the CCSID (coded character set identifier) currently 


in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented 
in the default CCSID of the job. 


See QlgUnlinkQ--Remove Link to File (using NLS-enabled path name) for a description and an 
example of supplying the path in any CCSID. 


Authorities 


Note: Adopted authority is not used. 


Figure 1-77. Authorization Required for unlink() (excluding QSYS.LIB, #*independent ASP 
QSYS.LIB, QDLS and QOPT) 


Pee ne ee 
Object Referred to Required errno 

[Each directory in the path name preceding the object tobe unlinked =————s«[*X———s [EACCES 
[Parent directory of the object to be unlinked [Wx [EACCES 
[Objecttobe unlinked KO BEXIST [EACCES. 


Figure 1-78. Authorization Required for unlink() in the QSYS.LIB #and independent ASP 
QSYS.LIB File Systems** 


Authority 
Object Referred to Required |errno 
[Each directory in the path name preceding the object to be unlinked [*x |EACCES 


[Parent directory of the object to be unlinked [See Note [EACCES 
[Object to be unlinked [See Note [EACCES 


Note: The required authorization varies for each object type. See the DLTxxx 


commands in the iSeries Security Reference eS book for details. 


Figure 1-79. Authorization Required for unlink() in the QDLS File System 


Fe | 
Object Referred to Required |errno 

[Each directory in the path name preceding the object tobe unlinked =—————«SSX———s [EACCCES. 
[Parent directory of the objecttobe unlinked = —i—i‘éO RX. ULEACCES 
[Object to be unlinked [*ALL [EACCES 


Figure 1-80. Authorization Required for unlink() in the QOPT File System 


Authority 
Object Referred to Required jerrno 


[Volume authorization list [*CHAN GE [EACCES 
Each directory in the path name preceding the object to be unlinked if volume *X EACCES 
media format is Universal Disk Format (UDF) 

Parent directory of the object to be unlinked if volume media format is Universal |*WX EACCES 
Disk Format (UDF) 


[Object to be unlinked if volume media format is Universal Disk Format (UDF) [*W [EACCES 


Object to be unlinked and parent directories if volume media format is not None None 
Universal Disk Format (UDF) 


Return Value 


0 
unlink() was successful. 
-] 


unlink() was not successful. The errno global variable is set to indicate the error. 


Error Conditions 


If unlink() is not successful, errno usually indicates one of the following errors. Under some conditions, 
errno could indicate an error other than those listed here. 


[EACCES] 
Permission denied. 
An attempt was made to access an object in a way forbidden by its object access permissions. 
The thread does not have access to the specified file, directory, component, or path. 
If you are accessing a remote file through the Network File System, update operations to file 
permissions at the server are not reflected at the client until updates to data that is stored locally by 
the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) 
command determine the time between refresh operations of local data.) Access to a remote file may 


also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote 
systems. 


[EAGAIN] 


Operation would have caused the process to be suspended. 
[EBADFID] 

A file ID could not be assigned when linking an object to a directory. 

The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as possible. 


[EBADNAME] 


The object name specified is not correct. 


[EBUSY] 


Resource busy. 


An attempt was made to use a system resource that is not available at this time. 


The file may be checked out. 


[ECONVERT] 


Conversion error. 


One or more characters could not be converted from the source CCSID to the target CCSID. 


[EDAMAGE] 


A damaged object was encountered. 


A referenced object is damaged. The object cannot be used. 


[EEXIST] 


File exists. 
The file specified already exists and the specified operation requires that it not exist. 


The named file, directory, or path already exists. 


[EFAULT] 


The address used for an argument is not correct. 
In attempting to use an argument in a call, the system detected an address that is not valid. 
While attempting to access a parameter passed to this function, the system detected an address that 


is not valid. 


[EFILECVT] 


File ID conversion of a directory failed. 


Try to run the Reclaim Storage (RCLSTG) command to recover from this error. 


[EINTR] 


Interrupted function call. 
[EINVAL] 
The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on an object and 
the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. 


[EIO] 


Input/output error. 
A physical I/O error occurred. 


A referenced object may be damaged. 


#”[EJRNDAMAGE] 
Journal damaged. 
A journal or all of the journal's attached journal receivers are damaged, or the journal sequence 


number has exceeded the maximum value allowed. This error occurs during operations that were 
attempting to send an entry to the journal. 


[EJRNENTTOOLONG] 


Entry too large to send. 


The journal entry generated by this operation is too large to send to the journal. 


[EJRNINACTIVE] 


Journal inactive. 


The journaling state for the journal is *INACTIVE. This error occurs during operations that were 
attempting to send an entry to the journal. 


[EJRNRCVSPC] 


Journal space or system storage error. 


The attached journal receiver does not have space for the entry because the storage limit has been 
exceeded for the system, the object, the user profile, or the group profile. This error occurs during 
operations that were attempting to send an entry to the journal. & 


[ELOOP] 


A loop exists in the symbolic links. 


This error is issued if the number of symbolic links encountered is more than POSIX_S YMLOOP 
(defined in the limits.h header file). Symbolic links are encountered during resolution of the 
directory or path name. 


[ENAMETOOLONG] 


A path name is too long. 


A path name is longer than PATH_MAX characters or some component of the name is longer than 
NAME_MAX characters while _POSIX_NO_TRUNC is in effect. For symbolic links, the length 
of the name string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and 
NAME_MAX values can be determined using the pathconf() function. 


#(ENEWJRN] 


New journal is needed. 


The journal was not completely created, or an attempt to delete it did not complete successfully. 
This error occurs during operations that were attempting to start or end journaling, or were 
attempting to send an entry to the journal. 


[ENEWJRNRCV] 
New journal receiver is needed. 
A new journal receiver must be attached to the journal before entries can be journaled. This error 


occurs during operations that were attempting to send an entry to the journal.*& 


[ENOENT] 
No such path or directory. 


The directory or a component of the path name specified does not exist. 


A named file or directory does not exist or is an empty string. 


[ENOMEM] 


Storage allocation request failed. 
A function needed to allocate storage, but no storage is available. 


There is not enough memory to perform the requested function. 


[ENOSPC] 
No space available. 
The requested operations required additional space on the device and there is no space left. This 
could also be caused by exceeding the user profile storage limit when creating or transferring 
ownership of an object. 


Insufficient space remains to hold the intended file, directory, or link. 


[ENOTAVAIL] 
Independent Auxiliary Storage Pool (ASP) is not available. 


The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage (RCLSTG) 
processing. 


To recover from this error, wait until processing has completed for the independent ASP. 


[ENOTSAFE] 


Function is not allowed in a job that is running with multiple threads. 
[ENOTDIR] 
Not a directory. 


A component of the specified path name existed, but it was not a directory when a directory was 
expected. 


Some component of the path name is not a directory, or is an empty string. 


[ENOTSUP] 
Operation not supported. 
The operation, though supported in general, is not supported for the requested object or the 


requested arguments. 


[EPERM] 


Operation not permitted. 


You must have appropriate privileges or be the owner of the object or other resource to do the 


requested operation. 


unlink() is not permitted on directories in this part of the directory hierarchy, or unlink() is 
permitted but the user does not have sufficient authority. 


[EROOBJ] 
Object is read only. 


You have attempted to update an object that can be read only. 


[ESTALE] 
File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may have been deleted 
at the server. 


[EUNKNOWN] 
Unknown system state. 


The operation failed because of an unknown system state. See any messages in the job log and 
correct any errors that are indicated, then retry the operation. 


[EXDEV] 
Improper link. 
A link to a file on another file system was attempted. 
If interaction with a file server is required to access the object, errno could indicate one of the following 
errors: 
[EADDRNOTAVAIL] 
Address not available. 
[ECONNABORTED] 
Connection ended abnormally. 
[ECONNREFUSED] 
The destination socket refused an attempted connect operation. 
[ECONNRESET] 
A connection with a remote socket was reset by that socket. 
[EHOSTDOWN] 
A remote host is not available. 
[EHOSTUNREACH] 
A route to the remote host is not available. 
[ENETDOWN] 
The network is not currently available. 
[ENETRESET] 


A socket is connected to a host that is no longer available. 


[ENETUNREACH] 
Cannot reach the destination network. 
[ESTALE] 
File or object handle rejected by server. 
If you are accessing a remote file through the Network File System, the file may have been deleted 
at the server. 
[ETIMEDOUT] 
A remote host did not respond within the timeout period. 
[EUNATCH] 


The protocol required to support the specified address family is not available at this time. 


Error Messages 


The following messages may be sent from this function: 
CPE3418 E 

Possible APAR condition or hardware failure. 
CPFAO0D4 E 

File system error occurred. Error number &1. 
CPF3CF2 E 

Error(s) occurred during running of &1 API. 
CPF9872 E 


Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 


1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 
oO Where multiple threads exist in the job. 


oO. The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


m Root 

m QOpenSys 

m User-defined 

a QNTC 

m QSYS.LIB 

m =Independent ASP QSYS.LIB & 
mw QOPT 


2. QSYS.LIB #and Independent ASP QSYS.LIB “File System Differences 


The link to a file cannot be removed when a job has the file open. 
The following object types cannot be unlinked when there are secondary threads active in the job: 
*CFGL, *CNNL, *COSD, *CTLD, *DEVD, *IPXD, *LIND, *MODD, *NTBD, *NWID, 
*NWSD. The operation will fail with error code [ENOTSAFE]. 

3. QDLS File System Differences 
The link to a document cannot be removed when a job has the document open (returns the 
[EBUSY] error). 

4. QOPT File System Differences 
The change and modification times of the parent directory are not updated. 


The link to a file cannot be removed when a job has the file open. 


Related Information 


e The <unistd.h> file (see Header Files for UNIX-Type Functions) 


e close()--Close File or Socket Descriptor 


e linkQ--Create Link to File 


@ open()--Open File 


e@ QlgOpen()--Open a File (using NLS-enabled path name) 


e QlgRmdir(--Remove Directory (using NLS-enabled path name) 
e QlgUnlinkQ--Remove Link to File (using NLS-enabled path name) 


e rmdir(Q--Remove Directory 


Example 
The following example removes a link to a file: 


#include <sys/types.h> 
#include <sys/stat.h> 
#include <fcntl.h> 
#include <unistd.h> 
#include <stdio.h> 


main() { 
int file_descriptor; 
char fn[]="unlink.file"; 


if ((file_descriptor = creat(fn, S_IWUSR)) < 0) 
perror ("creat() error"); 

else { 
close(file_descriptor); 


if (unlink(fn) != 0) 
perror("unlink() error"); 
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utime()--Set File Access and Modification 
Times 


Syntax 


#include <utime.h> 


int utime(const char *path, const struct utimbuf *times); 


Threadsafe: Conditional; see Usage Notes. 


The utime() function sets the access and modification times of path to the values in the utimbuf structure. If 
times is a NULL pointer, the access and modification times are set to the current time. If the named file is a 
symbolic link, utime() resolves the symbolic link. 


If the file is checked out by another user (someone other than the user profile of the current job), utime() 
fails with the [EBUSY] error. 


When utime() completes successfully, it marks the change time of the file to be updated. 


Parameters 


path 


(Input) A pointer to the null-terminated path name of the file for which the times should be 
changed. 


This parameter is assumed to be represented in the CCSID (coded character set identifier) currently 
in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented 
in the default CCSID of the job. 


See QlgUtime()--Set File Access and Modification Times (using NLS-enabled path name) for a 
description and an example of supplying the path in any CCSID. 


times 


(Input) A pointer to a structure utimbuf, which contains the times to be updated. 


The structure utimbuf is defined according to the POSIX.1 definition as follows: 


struct utimbuf { 
time_t actime; /* The new access time */ 
time_t modtime; /* The new modification time */ 


} 


The time_t type gives the number of seconds since the Epoch. 


Authorities 


Note: Adopted authority is not used. 


Figure 1-81. Authorization Required for utime() (excluding QDLS) 


Authority 
Object Referred to Required |errno 
[Each directory in the path name preceding the object *x [EACCES 


Object when changing the time to a specified value 


Object when changing the time to the current time 


[Note: You do not need the listed authority if you have *ALLOBJ special authority. 


Figure 1-82. Authorization Required for utime() in the QDLS File System 


Authority 
Object Referred to Required |errno 
[Each directory in the path name preceding the object [*x |EACCES 


[Object when changing the time to a specified value [Fw [EPERM 
[Object when changing the time to the current time [Fw [EACCES 


Return Value 


0 
utime() was successful. The file access and modification times are changed. 
-] 


utime() was not successful. The file times are not changed. The errno global variable is set to 
indicate the error. 


Error Conditions 


If utime() is not successful, errno usually indicates one of the following errors. Under some conditions, 
errno could indicate an error other than those listed here. 


[EACCES] 


Permission denied. 
An attempt was made to access an object in a way forbidden by its object access permissions. 
The thread does not have access to the specified file, directory, component, or path. 


If you are accessing a remote file through the Network File System, update operations to file 
permissions at the server are not reflected at the client until updates to data that is stored locally by 


the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) 
command determine the time between refresh operations of local data.) Access to a remote file may 
also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote 


systems. times is NULL and the job does not have authority to perform the requested function. 


[EAGAIN] 


Operation would have caused the process to be suspended. 
[EBADFID] 

A file ID could not be assigned when linking an object to a directory. 

The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as possible. 


[EBADNAME] 


The object name specified is not correct. 
[EBUSY] 
Resource busy. 


An attempt was made to use a system resource that is not available at this time. 


[ECONVERT] 


Conversion error. 


One or more characters could not be converted from the source CCSID to the target CCSID. 


[EDAMAGE] 


A damaged object was encountered. 


A referenced object is damaged. The object cannot be used. 


[EFAULT] 


The address used for an argument is not correct. 


In attempting to use an argument in a call, the system detected an address that is not valid. 


While attempting to access a parameter passed to this function, the system detected an address that 


is not valid. 


[EFILECVT] 


File ID conversion of a directory failed. 


Try to run the Reclaim Storage (RCLSTG) command to recover from this error. 


[EINTR] 


Interrupted function call. 
[EINVAL] 
The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on an object and 
the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. 


[EIO] 


Input/output error. 
A physical I/O error occurred. 


A referenced object may be damaged. 


[EISDIR] 


Specified target is a directory. 
The path specified named a directory where a file or object name was expected. 


The path name given is a directory. 


#*[EJRNDAMAGE] 


Journal damaged. 


A journal or all of the journal's attached journal receivers are damaged, or the journal sequence 
number has exceeded the maximum value allowed. This error occurs during operations that were 
attempting to send an entry to the journal. 


[EJRNENTTOOLONG] 
Entry too large to send. 


The journal entry generated by this operation is too large to send to the journal. 


[EJRNINACTIVE] 


Journal inactive. 


The journaling state for the journal is *INACTIVE. This error occurs during operations that were 
attempting to send an entry to the journal. 


[EJRNRCVSPC] 
Journal space or system storage error. 
The attached journal receiver does not have space for the entry because the storage limit has been 


exceeded for the system, the object, the user profile, or the group profile. This error occurs during 
operations that were attempting to send an entry to the journal.*& 


[ELOOP] 


A loop exists in the symbolic links. 


This error is issued if the number of symbolic links encountered is more than POSIX_SYMLOOP 
(defined in the limits.h header file). Symbolic links are encountered during resolution of the 
directory or path name. 


[ENAMETOOLONG] 


A path name is too long. 


A path name is longer than PATH_MAX characters or some component of the name is longer than 
NAME_MAX characters while POSIX_NO_TRUNC is in effect. For symbolic links, the length 
of the name string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and 
NAME_MAX values can be determined using the pathconf() function. 


#[ENEWJRN] 
New journal is needed. 
The journal was not completely created, or an attempt to delete it did not complete successfully. 


This error occurs during operations that were attempting to start or end journaling, or were 
attempting to send an entry to the journal. 


[ENEWJRNRCV] 
New journal receiver is needed. 
A new journal receiver must be attached to the journal before entries can be journaled. This error 


occurs during operations that were attempting to send an entry to the journal. 


[ENOENT] 
No such path or directory. 


The directory or a component of the path name specified does not exist. 


A named file or directory does not exist or is an empty string. 
[ENOMEM] 


Storage allocation request failed. 
A function needed to allocate storage, but no storage is available. 


There is not enough memory to perform the requested function. 


[ENOSPC] 
No space available. 
The requested operations required additional space on the device and there is no space left. This 
could also be caused by exceeding the user profile storage limit when creating or transferring 
ownership of an object. 


Insufficient space remains to hold the intended file, directory, or link. 


[ENOTAVAIL] 
Independent Auxiliary Storage Pool (ASP) is not available. 


The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage (RCLSTG) 
processing. 


To recover from this error, wait until processing has completed for the independent ASP. 


[ENOTDIR] 


Not a directory. 


A component of the specified path name existed, but it was not a directory when a directory was 
expected. 


Some component of the path name is not a directory, or is an empty string. 


[ENOTSAFE] 


Function is not allowed in a job that is running with multiple threads. 
[ENOTSUP] 
Operation not supported. 
The operation, though supported in general, is not supported for the requested object or the 


requested arguments. 


[EPERM] 


Operation not permitted. 


You must have appropriate privileges or be the owner of the object or other resource to do the 
requested operation. 


times is not NULL and the thread does not have authority to perform the requested function. 


[EROOBJ] 
Object is read only. 


You have attempted to update an object that can be read only. 


[ESTALE] 
File or object handle rejected by server. 
If you are accessing a remote file through the Network File System, the file may have been deleted 


at the server. 


[EUNKNOWN] 


Unknown system state. 


The operation failed because of an unknown system state. See any messages in the job log and 
correct any errors that are indicated, then retry the operation. 


If interaction with a file server is required to access the object, errno could indicate one of the following 
errors: 


[EADDRNOTAVAIL] 
Address not available. 
[ECONNABORTED] 
Connection ended abnormally. 
[ECONNREFUSED] 
The destination socket refused an attempted connect operation. 
[ECONNRESET] 
A connection with a remote socket was reset by that socket. 
[EHOSTDOWN] 
A remote host is not available. 
[EHOSTUNREACH] 
A route to the remote host is not available. 
[ENETDOWN] 
The network is not currently available. 
[ENETRESET] 
A socket is connected to a host that is no longer available. 
[ENETUNREACH] 
Cannot reach the destination network. 
[ESTALE] 
File or object handle rejected by server. 
If you are accessing a remote file through the Network File System, the file may have been deleted 
at the server. 
[ETIMEDOUT] 
A remote host did not respond within the timeout period. 
[EUNATCH] 


The protocol required to support the specified address family is not available at this time. 


Error Messages 


The following messages may be sent from this function: 
CPE3418 E 

Possible APAR condition or hardware failure. 
CPFA0D4 E 

File system error occurred. Error number &1. 
CPF3CF2 E 

Error(s) occurred during running of &1 API. 
CPF9872 E 


Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 


1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 
oO Where multiple threads exist in the job. 


oO The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


m Root 

m QOpenSys 

m User-defined 

gw QNTC 

mw QSYS.LIB 

m = Independent ASP QSYS.LIB & 
mw QOPT 


2. QSYS.LIB #and Independent ASP QSYS.LIB File System Differences 


These file systems do “not support utime(). 


3. QDLS File System Differences 


Changing the times of the /QDLS directory (the root folder) is not allowed. 


4. QOPT File System Differences 


The QOPT file system does not support utime(). 


5. QNTC File System Differences 


The QNTC file system does not set the access and modification times of path. The values in the 
utimbuf structure are ignored. 


Related Information 


e The <utime.h> file (see Header Files for UNIX-Type Functions) 


e The <limits.h> file (see Header Files for UNIX-Type Functions) 


e QleUtime(--Set File Access and Modification Times (using NLS-enabled path name) 


Example 
The following example uses utime(): 


#include <utime.h> 
#include <time.h> 
#include <stdio.h> 
#include <sys/types.h> 
#include <sys/stat.h> 
#include <fcntl.h> 


main() { 
int file_descriptor; 
char fn[]="utime.file"; 


struct utimbuf ubuf; 
struct stat info; 


if ((file_descriptor = creat(fn, S_IWUSR)) < 0) 
perror ("creat() error"); 
else { 
close(file_descriptor) ; 
puts ("before utime()"); 
stat (fn, &info); 
printf("  utime.file modification time is %ld\n", 
info.st_mtime) ; 
ubuf.modtime = 0; /* set modification time to Epoch */ 
time (&ubuf.actime) ; 
if (utime(fn, &ubuf) != 0) 
perror ("utime() error"); 
else { 
puts ("after utime()"); 
stat (fn, &info); 
printf("  utime.file modification time is %ld\n", 
info.st_mtime); 
} 


unlink (fn); 


} 


Output: 


before utime () 

utime.file modification time is 749323571 
after utime() 

utime.file modification time is 0 


API introduced: V3R1 
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write()--Write to Descriptor 


Syntax 


#include <unistd.h> 


ssize_t write 
(int file_descriptor, const void *buf, size_t nbyte); 


Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The write() function writes nbyte bytes from buf to the file or socket associated with file_descriptor. nbyte 
should not be greater than INT_MAX (defined in the <limits.h> header file). If nbyte is zero, write() simply 
returns a value of zero without attempting any other action. 


If file_descriptor refers to a "regular file" (a stream file that can support positioning the file offset) or any other 
type of file on which the job can do an Iseek() operation, write() begins writing at the file offset associated with 
file_descriptor, unless O_APPEND is set for the file (see below). A successful write() increments the file offset 
by the number of bytes written. If the incremented file offset is greater than the previous length of the file, the 
length of the file is set to the new file offset. 


If O_APPEND (defined in the <fentl.h> header file) is set for the file, write() sets the file offset to the end of 
the file before writing the output. 


If there is not enough room to write the requested number of bytes (for example, because there is not enough 
room on the disk), the writeQ) function writes as many bytes as the remaining space can hold. 


If write() is successful and nbyte is greater than zero, the change and modification times for the file are updated. 


If file_descriptor refers to a descriptor obtained using the open() function with O_TEXTDATA specified, the 
data is written to the file assuming it is in textual form. The maximum number of bytes on a single write that 
can be supported for text data is 2,147,483,408 (2GB - 240) bytes. The data is converted from the code page of 
the application, job, or system to the code page of the file as follows: 


e When writing to a true stream file, any line-formatting characters (such as carriage return, tab, and 
end-of-file) are just converted from one code page to another. 


e When writing to a record file that is being used as a stream file: 


o End-of-line characters are removed. 


oO Records are padded with blanks (for a source physical file member) or nulls (for a data physical 
file member). 


oO Tab characters are replaced by the appropriate number of blanks to the next tab position. 


There are some important considerations if O_CCSID was specified on the open(). 


e The write() will attempt to convert all of the data in the user's buffer. Successfully converted data will 
be written. Unconverted data is usually assumed to be a partial character. Partial characters will be 
buffered internally and data from the next consecutive write will be appended to the buffered data. If 
incorrect data is provided on a consecutive write, the write may fail with the [ECONVERT] error. 


If an Iseek() is performed, the file is closed, or the current job is ended, the buffered data will be 
discarded. Discarded data will not be written to the file. See lseek()--Set File Read/Write Offset for 


more information. 


e Because of the above consideration and because of the possible expansion or contraction of converted 
data, applications using the O_CCSID flag should avoid assumptions about data size and the current file 
offset. For example, the user may supply a buffer to 100 bytes, but after an application has written the 
buffer to a new file, the file size may be 50, 200, or something else, depending on the CCSIDs involved. 


If O_TEXTDATA was not specified on the open(), the data is written to the file without conversion. The 
application is responsible for handling the data. 


When file_descriptor refers to a socket, the write() function writes to the socket identified by the socket 
descriptor. 


Note: When the write completes successfully, the S_ISUID (set-user-ID) and S_ISGID (set-group-ID) bits of 
the file mode will be cleared. If the write is unsuccessful, the bits are undefined.> 


Write requests to a pipe or FIFO are handled the same as a regular file, with the following exceptions: 
e The S_ISUID and S_ISGID file mode bits will not be cleared. 


e There is no file offset associated with a pipe or FIFO. Each write request will append to the end of the 
pipe or FIFO. 


e Write requests of [PIPE_BUF] bytes or less will not be interleaved with data from other threads 
performing writes on the same pipe or FIFO. Writes of greater than [PIPE BUF] bytes may have data 
interleaved on arbitrary boundaries with writes by other threads, whether or not the O NONBLOCK 
flag of the file status flags is set. 


e If the O NONBLOCK flag was not specified and the pipe or FIFO is full, the write request will block 
the calling thread until the requested amount of data in nbyte is written. 


e If the O NONBLOCK flag was specified, then the following pertain to various write requests: 
oO The write() function will not block the calling thread. 


o A write request for [PIPE_BUF] or fewer bytes will have the following effect: 


If there is sufficient space available in the pipe or FIFO, write() will transfer all the data and 
return the number of bytes requested. If there is not sufficient space in the pipe or FIFO, write() 
will transfer no data, return -1, and set errno to [EAGAIN]. 


o A write request for more than [PIPE BUF] bytes will cause one of the following: 


mg When at least one byte can be written, write() will transfer what it can and return the 
number of bytes written. 


m= When no data can be written, write() will transfer no data, return -1, and set errno to 
[EAGAIN]. 


Parameters 


file_descriptor 


(Input) The descriptor of the file to which the data is to be written. 


buf 


(Input) A pointer to a buffer containing the data to be written. 


nbyte 
(Input) The size in bytes of the data to be written. 


Authorities 


No authorization is required. 


Return Value 


value write() was successful. The value returned is the number of bytes actually written. This number is 
less than or equal to nbyte. 


- write() was not successful. The errno global variable is set to indicate the error. 


Error Conditions 


If write() is not successful, errno usually indicates one of the following errors. Under some conditions, errno 
could indicate an error other than those listed here. 


[EACCES] Permission denied. 


An attempt was made to access an object in a way forbidden by its object access 
permissions. 


The thread does not have access to the specified file, directory, component, or 
path. 


If you are accessing a remote file through the Network File System, update 
operations to file permissions at the server are not reflected at the client until 
updates to data that is stored locally by the Network File System take place. 
(Several options on the Add Mounted File System (ADDMFS) command 
determine the time between refresh operations of local data.) Access to a remote 
file may also fail due to different mappings of user IDs (UID) or group IDs (GID) 
on the local and remote systems. 


If writing to a socket, this error code indicates one of the following: 


e The destination address specified is a broadcast address and the socket 
option SO_LBROADCAST was not set (with a setsockopt()). 


[EAGAIN] 


[EBADF] 


[EBADFID] 


[EBUSY] 


[EDAMAGE] 


[EFAULT] 


[EFBIG] 


2[EINTR] 


e The process does not have the appropriate privileges to the destination 
address. This error code can only be returned on a socket with an address 
family of AF_INET and a type of SOCK_DGRAM. 


Operation would have caused the process to be suspended. 


If file_descriptor refers to a pipe or FIFO that has its O_NONBLOCK flag set, this 
error occurs if the write() would have blocked the calling thread. 


Descriptor not valid. 


A file descriptor argument was out of range, referred to a file that was not open, or 
a read or write request was made to a file that is not open for that operation. 


A given file descriptor or directory pointer is not valid for this operation. The 
specified descriptor is incorrect, or does not refer to an open file. Or this write() 
request was made to a file that was only open for reading. 


A file ID could not be assigned when linking an object to a directory. 
The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon 
as possible. 


Resource busy. 

An attempt was made to use a system resource that is not available at this time. 
A damaged object was encountered. 

A referenced object is damaged. The object cannot be used. 

The address used for an argument is not correct. 


In attempting to use an argument in a call, the system detected an address that is 
not valid. 


While attempting to access a parameter passed to this function, the system 
detected an address that is not valid. 


Object is too large. 


The size of the object would exceed the system allowed maximum size #* or the 
process soft file size limit. 


The file is a regular file, nbyte is greater than 0, and the starting offset is greater 
than or equal to 2 GB minus 2 bytes. 


Interrupted function call.“ 


[EINVAL] 


[EIO] 


2[EJRNDAMAGE] 


[EJRNENTTOOLONG] 


[EJRNINACTIVE] 


[EJRNRCVSPC] 


[ENEWJRN] 


[ENEWJRNRCV] 


[ENOMEM] 


The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted 
on an object and the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. 


The file system that the file resides in does not support large files, and the starting 
offset exceeds 2GB minus 2 bytes. 


Input/output error. 

A physical I/O error occurred. 

A referenced object may be damaged. 
Journal damaged. 


A journal or all of the journal's attached journal receivers are damaged, or the 
journal sequence number has exceeded the maximum value allowed. This error 
occurs during operations that were attempting to send an entry to the journal. 


Entry too large to send. 
The journal entry generated by this operation is too large to send to the journal. 
Journal inactive. 


The journaling state for the journal is *INACTIVE. This error occurs during 
operations that were attempting to send an entry to the journal. 


Journal space or system storage error. 


The attached journal receiver does not have space for the entry because the storage 
limit has been exceeded for the system, the object, the user profile, or the group 
profile. This error occurs during operations that were attempting to send an entry 
to the journal. 


New journal is needed. 


The journal was not completely created, or an attempt to delete it did not complete 
successfully. This error occurs during operations that were attempting to start or 
end journaling, or were attempting to send an entry to the journal. 


New journal receiver is needed. 


A new journal receiver must be attached to the journal before entries can be 
journaled. This error occurs during operations that were attempting to send an 
entry to the journal. *& 


Storage allocation request failed. 
A function needed to allocate storage, but no storage is available. 


There is not enough memory to perform the requested function. 


[ENOSPC] 


[ENOTAVAIL] 


[ENOTSAFE] 


2 [ENXIO] 


[ERESTART] 


[ETRUNC] 


[ESTALE] 


[EUNKNOWN] 


No space available. 

The requested operations required additional space on the device and there is no 
space left. This could also be caused by exceeding the user profile storage limit 
when creating or transferring ownership of an object. 

Insufficient space remains to hold the intended file, directory, or link. 


Independent Auxiliary Storage Pool (ASP) is not available. 


The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage 
(RCLSTG) processing. 


To recover from this error, wait until processing has completed for the 
independent ASP. 


Function is not allowed in a job that is running with multiple threads. 
No such device or address. 

A system call was interrupted and may be restarted. 

Data was truncated on an input, output, or update operation. 


File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may 
have been deleted at the server. 


Unknown system state. 


The operation failed because of an unknown system state. See any messages in the 
job log and correct any errors that are indicated, thenretry the operation. 


When the descriptor refers to a socket, errno could indicate one of the following errors: 


[ECONNREFUSED] _ The destination socket refused an attempted connect operation. 


[EDESTADDRREO] 


[EHOSTDOWN] 


This error code can only be returned on sockets that use a connectionless transport 
service. 


Operation requires destination address. 


A destination address has not been associated with the socket pointed to by the fildes 
parameter. This error code can only be returned on sockets that use a connectionless 
transport service. 


A remote host is not available. 


This error code can only be returned on sockets that use a connectionless transport 
service. 


[EHOSTUNREACH] 


[EINTR] 


[EMSGSIZE] 


[ENETDOWN] 


[ENETUNREACH] 


[ENOBUFS] 


[ENOTCONN] 


[EPIPE] 


[EUNATCH] 


[EWOULDBLOCK] 


A route to the remote host is not available. 


This error code can only be returned on sockets that use a connectionless transport 
service. 


Interrupted function call. 


Message size out of range. 


The data to be sent could not be sent atomically because the size specified by nbyte is 
too large. 


The network is not currently available. 


This error code can only be returned on sockets that use a connectionless transport 
service. 


Cannot reach the destination network. 


This error code can only be returned on sockets that use a connectionless transport 
service. 


There is not enough buffer space for the requested operation. 


Requested operation requires a connection. 


This error code can only be returned on sockets that use a connection-oriented 
transport service. 


Broken pipe. 


The protocol required to support the specified address family is not available at this 
time. 


Operation would have caused the thread to be suspended. 


If interaction with a file server is required to access the object, errno could indicate one of the following errors: 


[EADDRNOTAVAIL] 


[ECONNABORTED] 


[ECONNREF USED] 


[ECONNRESET] 


[EHOSTDOWN] 


[EHOSTUNREACH] 


Address not available. 


Connection ended abnormally. 


The destination socket refused an attempted connect operation. 


A connection with a remote socket was reset by that socket. 


A remote host is not available. 


A route to the remote host is not available. 


[ENETDOWN] The network is not currently available. 

[ENETRESET] A socket is connected to a host that is no longer available. 
[ENETUNREACH] Cannot reach the destination network. 

[ESTALE] File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may 
have been deleted at the server. 


[ETIMEDOUT] A remote host did not respond within the timeout period. 
[EUNATCH] The protocol required to support the specified address family is not available at this 
time.> 


Error Messages 


The following messages may be sent from this function: 
Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF3CF2 E Error(s) occurred during running of &1 API. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 
CPFA081 E Unable to set return value or error code. 


CPFAOD4 E File system error occurred. Error number &1. 


Usage Notes 
1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 
oO Where multiple threads exist in the job. 


oO The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


m Root 
m QOpenSys 


m User-defined 


mw QNTC 

= QSYS.LIB 

m = Independent ASP QSYS.LIB & 
= QOPT 


2. QSYS.LIB # and independent ASP QSYS.LIB * File System Differences 


This function will fail with error code [ENOTSAFE] if the object on which this function is operating is 
a save file and multiple threads exist in the job. 


If the file specified is a save file, only complete records will be written into the save file. A write() 
request that does not provide enough data to completely fill a save file record will cause the partial 
record's data to be saved by the file system. The saved partial record will then be combined with 
additional data on subsequent write()'s until a complete record may be written into the save file. If the 
save file is closed prior to a saved partial record being written into the save file, then the saved partial 
record is discarded, and the data in that partial record will need to be written again by the application. 


A successful write() updates the change, modification, and access times for a database member using 
the normal rules that apply to database files. At most, the access time is updated once per day. 


You should be careful when writing end-of-file characters in the QSYS.LIB # and independent ASP 
QSYS.LIB file systems. These file systems *& end-of-file characters are symbolic; that is, they are 
stored outside the file member. However, some situations can result in actual, nonsymbolic end-of-file 
characters being written to a member. These nonsymbolic end-of-file characters could cause some tools 
or utilities to fail. For example: 


o. If you previously wrote an end-of-file character as the last character of a member, do not 
continue to write data after that end-of-file character. Continuing to write data will cause a 
nonsymbolic end-of-file to be written. As a result, a compile of the member could fail. 


o. If you previously wrote an end-of-file character as the last character of a member, do not write 
other end-of-file characters preceding it in the file. This will cause a nonsymbolic end-of-file to 
be written. As a result, a compile of the member could fail. 


o. If you previously used the integrated file system interface to manipulate a member that contains 
an end-of-file character, avoid using other interfaces (such as the Source Entry Utility or 
database reads and writes) to manipulate the member. If you use other interfaces after using the 
integrated file system interface, the end-of-file information will be lost. 


3. QOPT File System Differences 
The change and modification times of the file are updated when the file is closed. 


When writing to files on volumes formatted in Universal Disk Format (UDF), byte locks on the range 
being written are ignored. 


4. Network File System Differences 


Local access to remote files through the Network File System may produce unexpected results due to 
conditions at the server. Once a file is open, subsequent requests to perform operations on the file can 
fail because file attributes are checked at the server on each request. If permissions on the file are made 
more restrictive at the server or the file is unlinked or made unavailable by the server for another client, 
your operation on an open file descriptor will fail when the local Network File System receives these 
updates. The local Network File System also impacts operations that retrieve file attributes. Recent 
changes at the server may not be available at your client yet, and old values may be returned from 


operations (several options on the Add Mounted File System (ADDMEFS) command determine the time 
between refresh operations of local data). 


Reading and writing to files with the Network File System relies on byte-range locking to guarantee 
data integrity. To prevent data inconsistency, use the fentl() API to get and release these locks. 

5. QFileSvr.400 File System Differences 
The largest buffer size allowed is 16 megabytes. If a larger buffer is passed, the error EINVAL will be 
received. 


6. Sockets Usage Notes 


1. writeQ only works with sockets on which a connect() has been issued, since it does not allow 
the caller to specify a destination address. 


2. To broadcast on an AF_INET socket, the socket option SO.LBROADCAST must be set (with a 
setsockopt()). 


3. When using a connection-oriented transport service, all errors except [EUNATCH] and 
[EUNKNOWN] are mapped to [EPIPE] on an output operation when either of the following 
occurs: 


= A connection that is in progress is unsuccessful. 

m= Anestablished connection is broken. 
To get the actual error, use getsockopt() with the SO_ERROR option, or perform an input 
operation (for example, read()). 


7. For the file systems that do not support large files, write() will return [EINVAL] if the starting offset 
exceeds 2GB minus 2 bytes, regardless of how the file was opened. For the file systems that do support 
large files, writeQ) will return [EFBIG] if the starting offset exceeds 2GB minus 2 bytes and the file was 
not opened for large file access. 


8. Using this function successfully on the 4 /dev/null or /dev/zero *& character special file results in a 
return value of the total number of bytes requested to be written. No data is written to the character 
special file. In addition, the change and modification times for the file are updated. 


9. 2 If the write exceeds the process soft file size limit, signal SIFXFSZ is issued. 


Related Information 


e The <fentl.h> file (see Header Files for UNIX-Type Functions) 


e The <unistd.h> file (see Header Files for UNIX-Type Functions) 


@ creat()--Create or Rewrite File 


e dupQ--Duplicate Open File Descriptor 


e@ dup2Q--Duplicate Open File Descriptor to Another Descriptor 


e fentlQ--Perform File Control Command 

e ioctl()--Perform I/O Control Request 

e@ lseek()--Set File Read/Write Offset 

@ open()--Open File 

e * pread()--Read from Descriptor with Offset 

@ pread64()--Read from Descriptor with Offset (large file enabled) 
@ pwriteQ--Write to Descriptor with Offset 

@ pwrite64()--Write to Descriptor with Offset (large file enabled) 
e read()--Read from Descriptor 

e@ readv()--Read from Descriptor Using Multiple Buffers 

e send()--Send Data 

e sendmsg()--Send Data or Descriptors or Both 

e sendto()--Send Data 


@ writevQ--Write to Descriptor Using Multiple Buffers 


Example 


See Code disclaimer information for information pertaining to code examples. 


The following example writes a specific number of bytes to a file: 


#include <unistd.h> 
#include <sys/types.h> 
#include <sys/stat.h> 
#include <fcntl.h> 
#include <stdio.h> 


#define mega_string_len 1000000 


main() { 
char *mega_string; 
int file_descriptor; 
int ret; 
char fn[]="write.file"; 


if ((mega_string = (char*) malloc(mega_string_len)) == NULL) 
perror("malloc() error"); 

else if ((file_descriptor = creat (fn, S_IWUSR)) < 0) 

perror("creat() error"); 


else { 
memset (mega_string, 'O', 
if ((ret = write(file_descriptor, 
perror("write() error"); 
else printf("write() wrote %d bytes\n", 
if (close(file_descriptor) != 0) 
perror("close() error"); 
if (unlink(fn)!= 0) 
perror("unlink() error"); 


mega_string_len) ; 
mega_string, mega_string_len)) == 


ret); 


} 
Output: 


write() wrote 1000000 bytes 


API introduced: V3R1 
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writev()--Write to Descriptor Using Multiple 
Buffers 


Syntax 


#include <sys/types.h> 
#include <sys/uio.h> 


int writev(int descriptor, 


struct iovec *io_vector[], 
int vector_length) 


Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The writev() function is used to write data to a file or socket descriptor. writev() provides a way for the data 
that is going to be written to be stored in several different buffers (scatter/gather I/O). 


Note: When the write completes successfully, the S_ISUID (set-user-ID) and S_ISGID (set-group-ID) bits 
of the file mode will be cleared. If the write is unsuccessful, the bits are undefined. 


See write()--Write to Descriptor for more information related to writing to a descriptor. 


Parameters 


descriptor 


(Input) The descriptor to which the data is to be written. The descriptor refers to either a file or a 
socket. 


io_vector[| 


(Input) The pointer to an array of type struct iovec. struct iovec contains a sequence of pointers to 
buffers in which the data to be written is stored. The structure pointed to by the io_vector parameter 
is defined in <sys/uio.h>. 


struct iovec { 
void *iov_base; 
size_t iov_len; 


} 
iov_base and iov_len are the only fields in iovec used by sockets. iov_base contains the pointer to a 
buffer and iov_len contains the buffer length. The rest of the fields are reserved. 
vector_length 


(Input) The number of entries in io_vector. 


Authorities 


No authorization is required. 


Return Value 


writev() returns an integer. Possible values are: 


e -1 (unsuccessful) 


e n (successful), where n is the number of bytes written. 


Error Conditions 


If writev() is not successful, errno usually indicates one of the following errors. Under some conditions, 
errno could indicate an error other than those listed here. 


[EACCES] 


[EAGAIN] 


Permission denied. 


An attempt was made to access an object in a way forbidden by its object 
access permissions. 


The thread does not have access to the specified file, directory, component, or 
path. 


If you are accessing a remote file through the Network File System, update 
operations to file permissions at the server are not reflected at the client until 
updates to data that is stored locally by the Network File System take place. 
(Several options on the Add Mounted File System (ADDMEFS) command 
determine the time between refresh operations of local data.) Access to a 
remote file may also fail due to different mappings of user IDs (UID) or group 
IDs (GID) on the local and remote systems. 


If writing to a socket, this error code indicates one of the following: 


e The destination address specified is a broadcast address and the socket 
option SO_.BROADCAST was not set (with a setsockopt()). 


e@ The process does not have the appropriate privileges to the destination 
address. This error code can only be returned on a socket with an 
address family of AF_INET and a type of SOCK_DGRAM. 


Operation would have caused the process to be suspended. 


[EBADF] 


[EBADFID] 


[EBUSY] 


[EDAMAGE] 


[EFAULT] 


[EFBIG] 


2[EINTR] 


[EINVAL] 


Descriptor not valid. 


A file descriptor argument was out of range, referred to a file that was not 
open, or a read or write request was made to a file that is not open for that 
operation. 


A given file descriptor or directory pointer is not valid for this operation. The 
specified descriptor is incorrect, or does not refer to an open file. Or this 
writev() request was made to a file that was only open for reading. 


A file ID could not be assigned when linking an object to a directory. 
The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as 
soon as possible. 


Resource busy. 


An attempt was made to use a system resource that is not available at this 
time. 


A damaged object was encountered. 
A referenced object is damaged. The object cannot be used. 
The address used for an argument is not correct. 


In attempting to use an argument in a call, the system detected an address that 
is not valid. 


While attempting to access a parameter passed to this function, the system 
detected an address that is not valid. 


Object is too large. 


The size of the object would exceed the system allowed maximum size #*or 
the process soft file size limit. 


The file is a regular file, nbyte is greater than 0, and the starting offset is 
greater than or equal to 2GB minus 2 bytes. 


Interrupted function call.“ 


The value specified for the argument is not correct. 

A function was passed incorrect argument values, or an operation was 
attempted on an object and the operation specified is not supported for that 
type of object. 


An argument value is not valid, out of range, or NULL. 


The file resides in a file system that does not support large files, and the 
starting offset exceeds 2GB minus 2 bytes. 


[EIO] 


2*[EJRNDAMAGE] 


[EJRNENTTOOLONG] 


[EJRNINACTIVE] 


[EJRNRCVSPC] 


[ENEWJRN] 


[ENEWJRNRCV] 


[ENOMEM] 


[ENOSPC] 


Input/output error. 

A physical I/O error occurred. 

A referenced object may be damaged. 
Journal damaged. 


A journal or all of the journal's attached journal receivers are damaged, or the 
journal sequence number has exceeded the maximum value allowed. This 
error occurs during operations that were attempting to send an entry to the 
journal. 


Entry too large to send. 


The journal entry generated by this operation is too large to send to the 
journal. 


Journal inactive. 


The journaling state for the journal is *INACTIVE. This error occurs during 
operations that were attempting to send an entry to the journal. 


Journal space or system storage error. 


The attached journal receiver does not have space for the entry because the 
storage limit has been exceeded for the system, the object, the user profile, or 
the group profile. This error occurs during operations that were attempting to 
send an entry to the journal. 


New journal is needed. 


The journal was not completely created, or an attempt to delete it did not 
complete successfully. This error occurs during operations that were 
attempting to start or end journaling, or were attempting to send an entry to 
the journal. 


New journal receiver is needed. 
A new journal receiver must be attached to the journal before entries can be 


journaled. This error occurs during operations that were attempting to send an 
entry to the journal.“ 


Storage allocation request failed. 

A function needed to allocate storage, but no storage is available. 

There is not enough memory to perform the requested function. 

No space available. 

The requested operations required additional space on the device and there is 
no space left. This could also be caused by exceeding the user profile storage 


limit when creating or transferring ownership of an object. 


Insufficient space remains to hold the intended file, directory, or link. 


[ENOTAVAIL] 


[ENOTSAFE] 


#[ERESTART] 


[ESTALE] 


[ETRUNC] 


[EUNKNOWN] 


Independent Auxiliary Storage Pool (ASP) is not available. 


The independent ASP is in Vary Configuration (VRYCFG), or Reclaim 
Storage (RCLSTG) processing. 


To recover from this error, wait until processing has completed for the 
independent ASP. 


Function is not allowed in a job that is running with multiple threads. 


A system call was interrupted and may be restarted.*& 


File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file 
may have been deleted at the server. 


Data was truncated on an input, output, or update operation. 


Unknown system state. 


The operation failed because of an unknown system state. See any messages 
in the job log and correct any errors that are indicated, then retry the operation. 


When the descriptor refers to a socket, errno could indicate one of the following errors: 


[ECONNREFUSED] 


[EDESTADDRREQ] 


[EHOSTDOWN] 


[EHOSTUNREACH] 


[EINTR] 


[EMSGSIZE] 


The destination socket refused an attempted connect operation. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


Operation requires destination address. 


A destination address has not been associated with the socket pointed to by the 
fildes parameter. This error code can only be returned on sockets that use a 
connectionless transport service. 


A remote host is not available. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


A route to the remote host is not available. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


Interrupted function call. 


Message size out of range. 


The data to be sent could not be sent atomically because the size specified by 
nbyte is too large. 


[ENETDOWN] The network is not currently available. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


[ENETUNREACH] Cannot reach the destination network. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


[ENOBUFS] There is not enough buffer space for the requested operation. 


[ENOTCONN] Requested operation requires a connection. 


This error code can only be returned on sockets that use a connection-oriented 
transport service. 


[EPIPE] Broken pipe. 
[EUNATCH] The protocol required to support the specified address family is not available at 
this time. 


[EWOULDBLOCK] _ Operation would have caused the thread to be suspended. 


If interaction with a file server is required to access the object, errno could indicate one of the following 
errors: 

[EADDRNOTAVAIL] Address not available. 

[ECONNABORTED] Connection ended abnormally. 

[ECONNREFUSED] _ The destination socket refused an attempted connect operation. 

[ECONNRESET] A connection with a remote socket was reset by that socket. 

[EHOSTDOWN] A remote host is not available. 

[EHOSTUNREACH] _ A route to the remote host is not available. 

[ENETDOWN] The network is not currently available. 


[ENETRESET] A socket is connected to a host that is no longer available. 


[ENETUNREACH] Cannot reach the destination network. 


[ESTALE] File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may 
have been deleted at the server. 


[ETIMEDOUT] A remote host did not respond within the timeout period. 
[EUNATCH] The protocol required to support the specified address family is not available at 
this time. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF3CF2 E Error(s) occurred during running of &1 API. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 
CPFA081 E Unable to set return value or error code. 


CPFA0D4 E File system error occurred. Error number &1. 


Usage Notes 


1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 
oO Where multiple threads exist in the job. 


oO The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


m Root 

m QOpenSys 

m User-defined 

gw QNTC 

mw QSYS.LIB 

m *Independent ASP QSYS.LIB 
mw QOPT 


2. writev() only works with sockets on which a connect() has been issued, since the call does not 
allow the caller to specify a destination address. 


3. writev() is an atomic operation on sockets of type SOCK_DGRAM and SOCK_RAW in that it 


10. 


produces one packet of data every time it is issued. For example, a writev() to a datagram socket 
results in a single datagram. 


. To broadcast on an AF_INET socket, the socket option SO_.BROADCAST must be set (with a 


setsockopt()). 


. When using a connection-oriented transport service, all errors except [EUNATCH] and 


[EUNKNOWN] are mapped to [EPIPE] on an output operation when either of the following 
occurs: 


o Aconnection that is in progress is unsuccessful. 
o Anestablished connection is broken. 


To get the actual error, use getsockopt() with the SO_ERROR option, or perform an input operation 
(for example, read()). 


. For the file systems that do not support large files, writev() will return [EINVAL] if the starting 


offset exceeds 2GB minus 2 bytes, regardless of how the file was opened. For the file systems that 
do support large files, writev() will return [EFBIG] if the starting offset exceeds 2GB minus 2 
bytes and the file was not opened for large file access. 


. QFileSvr.400 File System Differences 


The largest buffer size allowed is 16 megabytes. If a larger buffer is passed, the error EINVAL will 
be received. 


. QOPT File System Differences 


When writing to files on volumes formatted in Universal Disk Format (UDF), byte locks on the 
range being written are ignored. 


. Using this function successfully on the dev/null #¥or /dev/zero “character special file results in a 


return value of the total number of bytes requested to be written. No data is written to the character 
special file. In addition, the change and modification times for the file are updated. 


“If the write exceeds the process soft file size limit, signal SIFXFSZ is issued. 


Related Information 


The <fentl.h> file (see Header Files for UNIX-Type Functions) 


The <unistd.h> file (see Header Files for UNIX-Type Functions) 
creat()--Create or Rewrite File 


dupQ--Duplicate Open File Descriptor 


dup2()--Duplicate Open File Descriptor to Another Descriptor 


fcentlQ--Perform File Control Command 


e ioctlO--Perform I/O Control Request 


e lseek()--Set File Read/Write Offset 


@ open()--Open File 


e@ read()--Read from Descriptor 


e@ readv()--Read from Descriptor Using Multiple Buffers 


e send()--Send Data 


e sendmsg()--Send Data or Descriptors or Both 


e@ sendtoQ--Send Data 


@ writeQ--Write to Descriptor 
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Process a Path Name Exit Program 


Required Parameter Group: 


Selection status pointer BINARY(4) 
Error value pointer BINARY(4) 


Return value pointer BINARY(4) 
Object name pointer CHAR(*) 
Function control block pointer CHAR(*) 


The Process a Path Name exit program is a user-specified exit program that is called by the 
Qp0IProcessSubtree() function for each object in the API's search that meets the caller's selection criteria. 
This exit program can be either a procedure or program. 


When the user exit program is given control, it can call other APIs, build lists or tables, or do other 
processing. Since the API passes the names of all the children objects to the user exit program before 
passing the name of the parent, the user exit program can also delete directories. 


If the exit program encounters an error during processing, it returns a valid errno in the Return value pointer 
field, that Qp0IProcessSubtree() returns to its caller. When its processing is complete, the exit program 
return code is set to tell Qp0IProcessSubtree() to do one of the following: 


e End processing. 


e Continue processing by calling the exit program again with the next object from the same directory. 


e Continue processing by calling the exit program again, but not with objects from the same 
directory. In this case, Qp0IProcessSubtree() moves to the next directory or object that meets the 
specified criteria and calls the exit program with it. 


If Qp0IProcessSubtree() encounters any problems in resolving to a user exit program, 
Qp0IProcessSubtree() ends and returns to its caller. If Qp0IProcessSubtree() encounters any errors with 
any other parameters, it ends and returns control to its caller, after a call to the user exit program. This call 
allows the exit program to perform any desired cleanup before Qp0IProcessSubtree() ends. Use the 
Err_recovery_action parameter of Qp0IProcessSubtree() to set other conditions for calling or not calling 
the user exit program. 


Storage referred to by the Selection status pointer, Error value pointer, Return value pointer, or the Object 
name pointer when the Process a Path Name exit program is called, are destroyed or reused when 
Qp0IProcessSubtree() regains control. 


See Qp01ProcessSubtree()--Process a Path Name for more information. & 


Parameters 


Selection status pointer 
INPUT; BINARY(4) 


A pointer to an unsigned integer. This pointer indicates whether Qp0IProcessSubtree() 


encountered any problems in processing. Valid values follow: 


0 QPOL_SELECT_OK: Indicates to that no problems were encountered during the selection of 
the current object. The Error value pointer parameter is set to NULL. 


I QPOL_SELECT_DONE: Indicates that the last object was processed and that this is the last 
call to the Process a Path Name exit program. The Object name pointer and the Error value 
pointer parameters are set to NULL. 


2 QPOL_SELECT_NOT_OK: Indicates that Qp0IProcessSubtree() has encountered an error 
but that the Process a Path Name exit program can decide if the operation should continue or 
end. The Error value pointer parameter points to a valid errno. 


3 QPOL_SELECT_FAILED: Indicates that Qp0IProcessSubtree() has encountered an 
unrecoverable error and that Qp0IProcessSubtree() will return to its caller when it regains 
control. The Error value pointer parameter points to a valid errno. 


Error value pointer 
INPUT; BINARY(4) 
A pointer to a valid errno that describes any problems encountered by the API during the 


processing of the current object. Any valid errno can be passed in this field when this parameter is 
not NULL. 


Return value pointer 
OUTPUT; BINARY(4) 


A pointer to a value from the Process a Path Name exit program that instructs the API to continue 
or to end processing. Valid values follow. 


0 Process a Path Name exit program was successful. 


-] Process a Path Name exit program was successful. Qp0IProcessSubtree() 
should skip processing any remaining objects in this directory and move on to 
process objects in other directories. 


> O/(anerrno) Process a Path Name exit program was not successful. 
Qp01ProcessSubtree() ends. 


Object name pointer 
INPUT; CHAR(*) 


A pointer to the path name structure that contains the fully qualified name of the object being 
processed by Qp0IProcessSubtree(). The Path_Type flag defined in the qlg-h header file must be 
used to determine whether the Object name pointer contains a pointer or is a character string. This 
flag must also be used to determine whether the path name delimiter character is 1 or 2 characters 
long. Value values follow: 


0 The path name is a character string, and the path name delimiter is 1 character long. 
I The path name is a pointer, and the path name delimiter character is 1 character long. 
2 The path name is a character string, and the path name delimiter is 2 characters long. 


3 The path name is a pointer, and the path name delimiter character is 2 characters long. 


Function control block pointer 
INPUT; CHAR(*) 


A pointer to the data that is passed to Qp01ProcessSubtree() on its call. Qp0IProcessSubtree() 
does not process the data that is referred to by this pointer, but passes this pointer as a parameter 
when it calls the exit program. 
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Save Storage Free Exit Program 


Required Parameter Group: 


Path name pointers Input Char(**) 


Return code pointer Output Binary(4) 
Return value pointer Output Binary(4) 
Function control block pointer Input Char(**) 


The Save Storage Free exit program is a user-specified program that is called by Qp0ISaveStgFree() to 
save an OS/400 object of type *STMF. This exit program can be either a procedure or program. 


When the Save Storage Free exit program is given control, it should save the object so it can be 
dynamically retrieved at a later time. The *STMF object is locked when the exit program is called to 
prevent changes to it until the storage free operation is complete. If the Save Storage Free exit program 
ends unsuccessfully, it must return a valid errno in the storage pointed to by the return value pointer. 
QpOlSaveStgFree() then passes this errno to its caller with a minus one return code. 


Storage referred to by the path name pointers or the return code pointer when the Save Storage Free exit 
program is called is destroyed or reused when Qp0ISaveStgFree() regains control. 


Required Parameter Group 


Path names pointers 
INPUT; CHAR(*) 


All of the path names to the *STMF object being storage freed. There is one path name for each 
link to the object. These path names are in the Qlg_Path_Name_T format and are in the UCS-2 
CCSID. See Path name format for more information on this format. For information about UCS-2, 


see the Globalization topic. 


Path Name Pointers 


| Offset 
| Dec Hex /Type Field 


| 0 0 BINARY(4) Number of path names 
| 4 4 CHAR(12) Reserved 
| 16 10 |ARRAY(*) Array of path name pointers 


Array of path name pointers. Pointers to each path name that Qp0ISaveStgFree() found for the 
object identified by the path name on the call to QpO0ISaveStgFree(). Each path name is in the 
Qlg_ Path_Name_T format. 


Number of path names. The total number of path names that Qp0ISaveStgFree() found for the 
object identified by the caller of Qp0ISaveStgFree(). 


Reserved. A reserved field. This field must be set to binary zero. 


Return code pointer 
OUTPUT; BINARY(4) 


A pointer to an indicator that is returned to indicate whether the exit program was successful or 
whether it failed. Valid values follow: 


O The Save Storage Free exit program was successful. 


-1 The Save Storage Free exit program was not successful. The Return value pointer is set to 
indicate the error. 


Return value pointer 
OUTPUT; BINARY(4) 
A pointer to a valid errno that is returned from the exit program to identify the reason it was not 
successful. 
Function control block pointer 
INPUT; CHAR(*) 
A pointer to the data that is passed to Qp0ISaveStgFree() on its call. Qp0ISaveStgFree() does not 


process the data that is referred to by this pointer, but passes this pointer as a parameter when it 
calls the exit program. 


Related Information 


e@ Qp0lSaveStgFree()--Save Storage Free 
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Integrated File System APls--Time Stamp 
Updates 


Each object (file and directory) has three time values associated with it: 
Access Time The time that the data in the object is accessed. 
Change Time The time that the attributes of the object are changed. 


Modify Time _ The time that the data in the object is changed. 


These values are returned by the stat(), fstat(), Istat(), 2and QlgStat()“£APIs. 


When it is stated that an API sets or updates one of these time values, the value may be "marked for update" 
by the API rather than actually updated. When a subsequent stat(), fstat(), Istat(), 2*and QlgStat()*& API is 
called, or the file is closed by all processes, the times that were previously "marked for update" are updated 
and the update marks are cleared. 


The value of these times is measured in seconds since the Epoch. The Epoch is the time 0 hours, 0 minutes, 
0 seconds, January 1, 1970, Coordinated Universal Time. If the system date is set prior to 1970, all time 
values will be zero. The following table shows which of these times are "marked for update" by each of the 
APIs. 
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. When the file did not previously exist, a successful creat() or QlgCreat() set the 
access, change, and modification times for the new file. It also sets the change and 
modification times of the directory that contains the new file (parent directory). 


. When the file previously existed, a successful creat() or QlgCreat() sets the change 
and modification times for the file. 


. The access time of each directory in the absolute path name of the current directory 
(excluding the current directory itself) is updated. 


. A successful linkQ or QlgLink() sets the change time of the file and the change and 
modification times of the directory that contains the new link (parent directory). 


. A successful mkdir() or QlgMkdir( sets the access, change, and modification times 
for the new directory. It also sets the change and modification times of the directory 
that contains the new directory (parent directory). 


. A successful mkfifoQ or QlgMkfifo() sets the access, change, and modification times 
for the new FIFO (first-in-first-out) special file. It also sets the change and 
modification times of the parent directory that contains the new FIFO file. 


. When O_CREAT is specified and the file did not previously exist, a successful open() 
or QlgOpen() sets the access, change, and modification times for the new file. It also 
sets the change and modification times of the directory that contains the new file 
(parent directory). 


. When O_TRUNC is specified and the file previously existed, a successful open() or 
QlgOpen( sets the change and modification times for the file. 


. When O_CREAT and O_TRUNC are not specified, open() or QlgOpen() does not 
update any time stamps. 


. A successful Qp0IGetPathFromFileIDQ or QlgGetPathFromFileIDQ sets the 
access time of each directory in the absolute path name to the file. 


. A successful symlink() or QlgSymlink() sets the access, change, and modification 
times for the new symbolic link. It also sets the change and modification times of the 
directory that contains the new directory (parent directory). 


. A successful unlink() or QlgUnlink() sets the change and modification times of the 
directory that contains the file being unlinked (parent directory). If the link count for 
the file is not zero, the change time for the file is set. 


. A successful utime() or QlgUtime() sets the access and modify times of the file as 
specified by the application. The change time of the file is set to the current time. 
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Header Files for UNIX-Type Functions 


Programs using the UNIX-type functions must include one or more header files that contain information 
needed by the functions, such as: 


e Macro definitions 
e Data type definitions 
e Structure definitions 
e Function prototypes 
The header files are provided in the QS YSINC library, which is optionally installable. Make sure 


QSYSINC is on your system before compiling programs that use these header files. For information on 
installing the QSYSINC library, see Data structures and the QSYSINC Library. 


The table below shows the file and member name in the QS YSINC library for each header file used by the 
UNIX-type APIs in this publication. 


Name of File in 
Name of Header File QSYSINC Name of Member 


[| arpa/ineth [| arpa/ineth [ ARPA [INET 


a 
a * 

tik | | so 
[  —sbseerrch CEC A~<“‘i‘~*Y:S*é‘éiBSEERRR 
[ss direnth [CM Rs—~<“i«i‘Cé«zYS)~OCéIRENT 
[ emoh [| H [ERRNO] | 
[_eph | SOS 

| evinttypes. h | | TNS 
ee ee ee 
[| %netinet/iemp6.h NETINE |  ICMP6& 
[| netinetinh NETINET [| WN 
| netinet/ip_icmp.h NETINET [|  IPICMP 


mo) oo) eo) eo) a) ee} ee} ey] 


| netinet/ip.h NETINET | IP 
| 2’netinet/ip6.h NETINET | IP6& 
| netinet/tcp.h NETINET TCP 


| netinet/udp.h NETINET UDP 

[netns/idph = | 0S NETNS) [CIDP 
[netns/ipxh = |S NETNS) [CPX 
[so netns/ns-h | NETNS) [CONST 
[so netns/sp-b |S NETNS) [SP 
[netrouteh = [)CNET)=—~<C;«é‘L”)~Ss*'<‘éROUTEECi:*s 
[—snettel/telLh «= sis[))sSNETTEL =o [)ti‘<‘STENRES—“( isis 


an 


[  oosh fC OS2 

[|  —sosddefh fC ASE S2DEF 
[ pwd fC PWD 

[0 gh fH QLG 

| —s qpOlfloph fs QPOLFLOP 
| Bqp0limih | | QPOLIRNLE 

| 2>qpOlror.h | | QPOLROR& 

|  qpOzolsm-h fC HH—C*ST ss QPOZOLSM 
| — qpOztrech fC QPOZTRE 
|  qpOztrmlh [| CSTs QPOZTRML 
| #qsoasync.h | | QSOASYNC% 
| qtnxaapi.h | QTNXAAPI 
[ qtnxadtph fC H——CSE ss QQTNXADTP 
|  qtomeapih sf] CM ™—C~@TSsC QQOMEEAP 


TRIG 


| qtossapi.h | H | QTOSSAPI 
| resolv.h | H | RESOLVE 


an 


| semaphore.h | | SEMAPHORE 


[signal | CMHC SIGNAL 
[|  spawnh Cf CM ™~“<~S SPAWN 
[ssh fA SSL 

| sysferrnoh = fC H™:~iT SC ERRNOU 
[| sysfioctLh SYS [|  IOCTL 
| ——ssys/ipeh SYS [ woe 


| sys/layout.h | H | LAYOUT 
| sys/limits.h | H | LIMITS 


| —ssys/msg-ho SYS MSG 

[| sys/param.h SYS [ PARAM 
| #*sys/resource.h SYS | RESOURCE® 

| —ssys/sem-h SYS SEM 

| sys/setimp.h SYS | ‘SETIMP 
| sys/shm.h SYS SHM 

[| sys/signalh SYS [ SIGNAL 
[| _sys/socketh SYS [SOCKET 
[| —sys/stath SYS [ STAT” 


| sys/statvfs.h SYS | STATVFS 


| —ssysfimeh SYS [| TIME 
[| sys/types.b SYS [TYPES si 
| —ssys/uio.h SYS UIO 

[ sys SYS [ UN 
| —ssys/waith SYS | WAIT 
| Sulimit.h H | ULIMIT*& 

[| sounistdh fC HSE UNISTD 
[  soutimeh fC UTIME 


You can display a header file in QS YSINC by using one of the following methods: 


e Using your editor. For example, to display the unistd.h header file using the Source Entry Utility 
editor, enter the following command: 


STRSEU SRCFILE(QSYSINC/H) SRCMBR(UNISTD) OPTION(5) 


e Using the Display Physical File Member command. For example, to display the sys/stat.h header 
file, enter the following command: 


DSPPFM FILE(QSYSINC/SYS) MBR(STAT) 


You can print a header file in QSYSINC by using one of the following methods: 


e Using your editor. For example, to print the unistd.h header file using the Source Entry Utility 
editor, enter the following command: 


STRSEU SRCFILE(QSYSINC/H) SRCMBR(UNISTD) OPTION (6) 
e Using the Copy File command. For example, to print the sys/stat.h header file, enter the following 


command: 


CPYF FROMFILE(QSYSINC/SYS) TOFILE(*PRINT) FROMMBR (STAT) 


Symbolic links to these header files are also provided in directory /QIBM/include. 


Top | UNIX-Type APIs | APIs by category 


Errno Values for UNIX-Type Functions 


Programs using the UNIX-type functions may receive error information as errno values. The possible 
values returned are listed here in ascending errno value sequence. 


[Name [Value [Test 

~——— a ee domain error occurred in a math 
function. 

[ERANGE = GE [300200 A [Arangeerror occurred. = error [Arangeerror occurred. = 

—| C _— Data was truncated on an input, output, or 
update operation. 

EN [ENOTOPEN [3004 [Fileisnotopen. is not [Fileisnotopen. 


—— OTREAD — [File i is not opened for read operations. 
EIO [3006 [Input/output error. 


EN [ENODEV [3007 N [Nosuchdevice. [Nosuchdevice. device. 

ae —_ Cannot get single character for files 
opened for record I/O. 

EN [ENOTWRITE [30090 [File is not opened for write operations. is not [File is not opened for write operations. for write operations. 


a —— [The stdin stream cannot be opened. 
[ESTDOUT [3011 [The stdout stream cannot be opened. 


[ESTDERR [30120 [The stderr stream cannot be opened. stderr stream cannot be [The stderr stream cannot be opened. 

_—| a The positioning parameter in fseek is not 
correct. 

[EBADNAME AME [30140 [The object name specified is not correct. — [The object name specified is not correct. — name specified is not correct. 


a ——! The type variable specified on the open 
function is not correct. 


[EBADPOS 3017s [The position specifier is not correct. position [The position specifier is not correct. is not correct. 


17 
EN a — There is no record at the specified 
position. 
ENUMMBRS 3019 Attempted to use ftell on multiple 
members. 
ENUMRECS 3020 The current record position is too long for 
ftell. 
EINVAL 3021 The value specified for the argument is not 
correct. 
EBADFUNC 3022 Function parameter in the signal function 
is not set. 
[302500 


EN [ENOENT T No [No such path or directory, = [No such path or directory, = or directory. 


FoR? ——— ht’ —— ae 
[EPERM  =——<CS~s«LB27_~——SSC«*d Phe Oplerationn is not permitted. = 
[EBADDATA  ——s[3028——Ss[Meessage dataisnotvalid. = 
[EBUSY ==—=«S(38029—s Resource busy, 
[EBADOPT —s*(3040 = Option specified is not valid. 
[ENOTUPD ~—s*([3041 =~‘ File is not opened for update operations. 
[ENOTDLT ~—*[3042. [File is not opened for delete operations. 


EPAD 3043 The number of characters written is 
shorter than the expected record length. 

EBADKEYLN 3044 A length that was not valid was specified 
for the key. 

EPUTANDGET 3080 A read operation should not immediately 
follow a write operation. 

EGETANDPUT 3081 A write operation should not immediately 
follow a read operation. 

[EIOERROR [3101 [A nonrecoverable I/O error occurred. 

[EIORECERR [3 102 [A recoverable I/O error occurred. 

[EACCES [3401 [Permission denied. 


[EN OTDIR [3403 [N ot a directory. 
[ENOSPC [3404 [No space is available. 


[EXDEV [3405 Improper link, [Improperlink, 


[34050 
aa_— 3406 Operation would have caused the process 
to be suspended. 
EWOULDBLOCK 3406 Operation would have caused the process 
to be suspended. 
[3407 


[EINTR [3407 SS s‘[Interrupted function call. [Interrupted function call. call. 


ee— 3408 The address used for an argument was not 
correct. 


[ETIME [3409 [3409 [Operation timedout. [Operation timedout. out. 
—_——— [3415 0 No [No such device oraddress. device [No such device oraddress. address. 
SEs i Pa 
failure 
[ERECURSE [3419 [Recursive attempt rejected. = attempt [Recursive attempt rejected. = 
 ORNESE Si —— see 
[EADDRNOTAVAIL [342200 [Address is notavailable. = [Address is notavailable. = not available. 
ESINOSUORT > pean type of socket is not supported in this 
protocol family. 
[EALREADY [342300 [3423 [Operation is already in progress. = is already in progress. 
REE ABORTED [34240000 [Connection ended abnormally. ended [Connection ended abnormally. 
25 


ECONNRTUSED — aS rma ba tn te 
connect operation 
i ae ce 
reset by that socket 
[EDESTADDRREQ. [3427 00 [3427 | Operation requires destination address. requires [Operation requires destination address. address. 
[EHOSTDOWN [3428s {Ar remote host is notavailable. 
[EHOSTUNREACH [3429 ‘A route to the remote host is not available. 
[EINPROGRESS —[3430. Ss |Operationin progress. = 
[EISCONN «(3431s {A connection has already been established. 
[EMSGSIZE «(3432s [Message size isoutofrange. 
[ENETDOWN  ——s[3433.—s*[ The network currently is not available. 


ENETRESET 3434 A socket is connected to a host that is no 
longer available. 


[ENETUN REACH [3435 [Cannot reach the destination network. 

ENOBUFS 3436 There is not enough buffer space for the 
requested operation. 

ENOPROTOOPT 3437 The protocol does not support the 

specified option. 

ENOTCONN 3438 Requested operation requires a 
connection. 

ENOTSOCK 3439 The specified descriptor does not 
reference a socket. 

[EN OTSUP [3440 [Operation is not supported. 

[EOPN OTSUPP [3440 [Operation is not supported. 


EPFNOSUPPORT 3441 The socket protocol family is not 
supported. 

EPROTONOSUPPORT |3442 No protocol of the specified type and 
domain exists. 

EPROTOTYPE 3443 The socket type or protocols are not 
compatible. 

ERCVDERR 3444 An error indication was sent by the peer 
program. 


[ESHUTDOWN [3445 [Cannot send data after a shutdown. 
[ESOCKTN OSUPPORT [3446 [The specified socket type is not supported. 


ETIMEDOUT 3447 A remote host did not respond within the 
timeout period. 

EUNATCH 3448 The protocol required to support the 
specified address family is not available at 
this time. 


[EBADF = =—S—=«&;3'45——SsDescriptorisnot valid, 
[EMFILE  =—S*[3452,—S——Ss {Too many open files for this process. 
[ENFILE =——=S&3453. Ss [Too many open files inthe system. 
EPIPE == ~—«*(3455, ss (Brokenpipe. 
[ECANCEL =——s«[3456.———s|Operationcancelled. = 
[EEXIST =———s«*(3'KST_—— sie exists, 
[EDEADLK =——s*[3459_ Resource deadlock avoided. 
[ENOMEM ——s«[3460—Ss« Storage allocation request failed. = 
62 


a 34 The synchronization object no longer 
exists because the owner is no longer 
running. 

EDESTROYED 3463 The synchronization object was destroyed, 
or the object no longer exists. 

[ETERM [3464 00—CO [3464 Operation was terminated. = was [Operation was terminated. = 


aes —— OENT1 [3 465 [N o such file or directory. 


ENOEQFLOG 3466 Object is already linked to a dead 
ones sag 


[EEMPTYDIR [3 467 [Directoryisempty. = is empty. 


EMLINK 3468 Maximum link count for a file was 
exceeded. 


ESPIPE  =—~SC~«&346—— “Seek request is not supported for object. 
[ENOSYS —————=«*3470.—S—SSs|Function not implemented. = 
[EISDIR ——i(ass—t*é«*BATALC Specified targetisadirectory, = 
[EROFS =———~—é«i;3B220-—— Read-only file system. 
[EUNKNOWN  —s[3474.— ss [Unknown system state. = 
[EITERBAD  =——s«(34750—— iterator isnotvalid. = 
[EITERSTE  =—sS*(3476 ~—S—SCs=|Iterator is in wrong state for operation. 
[EHRICLSBAD —s [3477 Ss HIRI classisnotvalid. 
[EHRICLBAD ~—s([3478 = {IRI subclassisnot valid. = 
[EHRITYPBAD —[3479 Ss {HRI typeisnotvalid, = 
[ENOTAPPL —=—s*[3480.—~——Ss [Datta requested is not applicable. = 
[EHRIREQTYP  =—[3481_ = {ARI request type isnot valid. 
[EHRINAMEBAD —_ [3482s {HRT resource name isnot valid. 
[EDAMAGE —s([3484.————s [A damaged object was encountered. 
[ELOOP  ———~™—=é«S;3485— SA cop exists in the symbolic links. 
[ENAMETOOLONG [3486 = {Apathnameistoolong, 
[ENOLCK = =——s«*(3487,——s No locksare available. = 
[ENOTEMPTY —*[3488 ~=——Ss[Directory isnotempty. = 
[ENOSYSRSC [3489s System resources are not available. = 
[ECONVERT =— [3490s |Conversionerror, 


[E2BIG [3491 [3491 Ss [Argumentlististoolong, [Argument lististoolong, = is too long. 
—=———— 3492 Conversion stopped due to input character 
that does not belong to the input codeset. 


[ETYPE  ——™ [3493 [3493 |Objecttypemismatche type [Object type mismatch, 
—— 3494 Attempted to reference a directory that 
was not found or was destroyed. 
EBADOBJ 3495 Attempted to reference an object that was 
not found, was destroyed, or was 
damaged. 
EIDXINVAL 3496 Data space index used as a directory is not 
valid. 
[ESOFTDAMAGE [3497 [3497 [Objecthas softdamage. [Objecthas softdamage. soft damage. 


Soe | OTENROLL 3498 User is not enrolled in system distribution 
ies sae———— 


[EOFFLINE = 3499 [3499 |Objectissuspended. is suspended. 


[34990 
oe —— [3 500 [Object i is a read-only object. 


EEAHDDSI 3501 Hard damage on extended attribute data 
space index. 

EEASDDSI 3502 Soft damage on extended attribute data 
space index. 

EEAHDDS 3503 Hard damage on extended attribute data 
space. 

EEASDDS 3504 Soft damage on extended attribute data 

| | ee 


[EEADUPRC [3505 [Duplicate extended attribute record. 


ELOCKED 3506 Area being read from or written to is 
locked. 


[EFBIG [3507 [3507 ss |Objecttoolarge. [Objecttoolarge, large. 
509 


a—_—— 3 The semaphore, shared memory, or 
message queue identifier is removed from 
the system. 

OMSG e The queue does not contain a message of 


the desired type and (msgflg logically 
ANDed with IPC_NOWAIT). 


[EFILECVT = [351k [File ID conversion of a directory failed. ID conversion of a [File ID conversion of a directory failed. failed. 

a——— _— A file ID could not be assigned when 
linking an object to a directory. 

[ESTALE [3513 [File handle was rejected by server. handle was [File handle was rejected by server. by server. 


es} — oes 
[ENOTSIGINIT ——[3516 [Process is not enabled for signals. 

[ECHILD  =———~—=«~S(;B'SS'T.— Ss Nochild process. 
[EBADH = =—sS«(3520.——sHandleisnotvalid, = 


iN YREFS 3523 The operation would have exceeded the 


maximum number of references allowed 
for a descriptor. 


[ENOTSAFE =——s [3524s |Functionisnotallowed. = 
ESC aW—— sk —— pice ee ——— 
[EIRNDAMAGE ~—[3526 Ss |Jourmalisdamaged. 
[EJRNINACTIVE ~— [3527s |Jourmalisimactive, = 
[EIRNRCVSPC [3528 = s‘|Journal space or system storage error. 
[EIRNRMT = ——s*(3529, Ss Journalisremote. 
[ENEWJRNRCV [3530s [New journal receiver isneeded. 
[ENEWJRN  ———s«(3531.=——Ss New journalisneeded. = 
[EJOURNALED [3532s Objectalready journaled. = 
[EIRNENTTOOLONG 3533 [Entry istoolargetosend. 
[EDATALINK —s [3534s [Object is adatalink object. 
[ENOTAVAIL ~—s 3535. IASPisnotavailable. = 


[ENOTTY = OTTY [35360 [I/O control operation is not appropriate. control [I/O control operation is not appropriate. is not appropriate. 

sues 3540 Attempt to write or truncate file past its 
=o ie file size limit. 

[ETXTBSY [35430 [Textfilebusy. file [Textfilebusy. 

SENG OTSET ~— [ASP group not set forthread. [ASP group not set forthread. not set for thread. 


—— a A system call was interrupted and may be 
restarted. 
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